From 67c9bae63cb8c182b14e06cc52591c7b121749da Mon Sep 17 00:00:00 2001 From: Elmer Thomas Date: Wed, 2 Mar 2016 06:07:03 -0800 Subject: [PATCH] Version Bump v1.0.0 --- CHANGELOG.md | 8 + LICENSE | 2 +- README.md | 15 +- raml.yaml | 28173 +++++++++++------------ swagger-stoplight.json => swagger.json | 423 +- swagger.yaml | 19813 ++++++++-------- temp.json | 18278 --------------- 7 files changed, 24022 insertions(+), 42690 deletions(-) create mode 100644 CHANGELOG.md rename swagger-stoplight.json => swagger.json (96%) delete mode 100644 temp.json diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..265675b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,8 @@ +# Change Log +All notable changes to this project will be documented in this file. + +## [1.0.0] - 2016-03-01 ## + +### Added ### + +- Swagger.json, Swagger.yaml and RAML.yaml files open sourced \ No newline at end of file diff --git a/LICENSE b/LICENSE index 21f62a8..aaa5589 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2015 SendGrid +Copyright (c) 2016 SendGrid Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 1974c85..27343e3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,14 @@ -# Obtaining the Swagger File +[![Travis Badge](https://travis-ci.org/sendgrid/python-http-client.svg?branch=master)](https://travis-ci.org/sendgrid/python-http-client) -Inside your stoplight.io account, click the "Export API" dropdown menu and right click on "Swagger 2.json" and choose "Save as". +**This is a Swagger 2.0 and RAML 0.8 representation of the [SendGrid v3 Web API](v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html).** -To pretty print use: +If you have an interesting use case for these files or have a request, please [let us know via email](mailto:dx@sendgrid.com) or [create an issue](https://github.com/sendgrid/sendgrid-swagger/issues). -`python -m json.tool my_json.json` +# About + +![SendGrid Logo] +(https://assets3.sendgrid.com/mkt/assets/logos_brands/small/sglogo_2015_blue-9c87423c2ff2ff393ebce1ab3bd018a4.png) + +sendgrid-swagger is guided and supported by the SendGrid [Developer Experience Team](mailto:dx@sendgrid.com). + +sendgrid-swagger is maintained and funded by SendGrid, Inc. The names and logos for sendgrid-python are trademarks of SendGrid, Inc. diff --git a/raml.yaml b/raml.yaml index 120983f..9dbb895 100644 --- a/raml.yaml +++ b/raml.yaml @@ -1,5 +1,5 @@ #%RAML 0.8 -title: DX - Web API v3 - Officially Documented Only +title: DX - v3 - Officially Documented Only - DO NOT EDIT version: '3.0' baseUri: 'https://api.sendgrid.com/v3' mediaType: application/json @@ -7,7 +7,7 @@ protocols: - HTTP - HTTPS documentation: - - title: DX - Web API v3 - Officially Documented Only + - title: DX - v3 - Officially Documented Only - DO NOT EDIT content: "# 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\n\n" /partner_settings: displayName: partner_settings @@ -16,19 +16,6 @@ documentation: displayName: sendwithus description: '' uriParameters: {} - get: - displayName: Get SendWithUs Settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - queryParameters: {} patch: displayName: Update SendWithUs Settings body: @@ -59,12 +46,8 @@ documentation: } example: '' queryParameters: {} - /new_relic: - displayName: new_relic - description: '' - uriParameters: {} get: - displayName: Get new relic partner settings + displayName: Get SendWithUs Settings headers: {} responses: '200': @@ -72,17 +55,22 @@ documentation: application/json: schema: |- { - "$ref": "#/definitions/partner_settings_new_relic" - } - example: |- - { - "enable_subuser_statistics": false, - "enabled": true, - "license_key": "" + "type": "object" } + example: '' queryParameters: {} + /new_relic: + displayName: new_relic + description: '' + uriParameters: {} patch: - displayName: Update new relic partner settings + displayName: Updates New Relic partner settings. + description: |- + **This endpoint allows you to update or change your New Relic partner settings.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). body: application/json: example: |- @@ -96,13 +84,16 @@ documentation: "type": "object", "properties": { "license_key": { - "type": "string" + "type": "string", + "description": "The license key for your New Relic account." }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Indicates if this partner setting is enabled." }, "enable_subuser_statistics": { - "type": "boolean" + "type": "boolean", + "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." } } } @@ -122,9 +113,37 @@ documentation: "license_key": "" } queryParameters: {} + get: + displayName: Returns all New Relic partner settings. + description: |- + **This endpoint allows you to retrieve your current New Relic partner settings.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/partner_settings_new_relic" + } + example: |- + { + "enable_subuser_statistics": false, + "enabled": true, + "license_key": "" + } + queryParameters: {} uriParameters: {} get: - displayName: Get partner settings + displayName: Returns a list of all partner settings. + description: |- + **This endpoint allows you to retrieve a list of all partner settings that you can enable.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). headers: {} responses: '200': @@ -136,23 +155,32 @@ documentation: "properties": { "result": { "type": "array", - "_isOpen": true, "items": { "type": "object", "properties": { "title": { - "type": "string" + "type": "string", + "description": "The title of the partner." }, "enabled": { - "type": "boolean" + "type": "boolean", + "description": "Indicates if this partner setting has been enabled." }, "name": { - "type": "string" + "type": "string", + "description": "The name of the partner setting." }, "description": { - "type": "string" + "type": "string", + "description": "A description of this partner setting." } - } + }, + "required": [ + "title", + "enabled", + "name", + "description" + ] } } } @@ -170,395 +198,168 @@ documentation: } queryParameters: limit: - type: string - undefined: - type: string -/subusers: - displayName: subusers + type: integer + description: The number of settings to return per page. + offset: + type: integer + description: The paging offset. +/asm: + displayName: asm description: '' - /stats: - displayName: stats + /groups: + displayName: groups description: '' - uriParameters: {} - get: - displayName: Subuser Stats provide all of your user’s email statistics for your subuser accounts. - headers: {} - responses: - '200': + '/{group_id}': + displayName: '{group_id}' + description: '' + uriParameters: + group_id: + type: string + delete: + displayName: Delete a suppression group. + description: |- + **This endpoint allows you to delete a suppression group.** + + You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list. + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + queryParameters: {} + /suppressions: + displayName: suppressions + description: '' + uriParameters: {} + get: + displayName: Retrieve all suppressions for a suppression group + description: |- + **This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.** + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "string" + } + } + example: |- + [ + "example@example.com", + "example2@example.com" + ] + queryParameters: {} + '/{email}': + displayName: '{email}' + description: '' + uriParameters: + email: + displayName: The email address that you want to remove from the suppression group. + type: string + delete: + displayName: Delete a suppression from a suppression group + description: |- + **This endpoint allows you to remove a suppressed email address from the given suppression group.** + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "null" + } + example: '' + queryParameters: {} + post: + displayName: Add suppressions to a suppression group + description: |- + **This endpoint allows you to add email addresses to an unsubscribe group.** + + If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list. + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. body: application/json: + example: |- + { + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] + } schema: |- { - "type": "array", - "items": { + "type": "object", + "properties": { + "recipient_emails": { + "type": "array", + "description": "The email address that you want to add to the unsubscribe group.", + "items": { + "type": "string" + } + } + }, + "required": [ + "recipient_emails" + ] + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { "type": "object", "properties": { - "date": { - "type": "string" - }, - "stats": { + "recipient_emails": { "type": "array", + "description": "The email address that were added to the suppressions list.", "items": { - "properties": { - "type": { - "type": "string" - }, - "name": { - "type": "string" - }, - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "number" - }, - "bounce_drops": { - "type": "number" - }, - "bounces": { - "type": "number" - }, - "clicks": { - "type": "number" - }, - "deferred": { - "type": "number" - }, - "delivered": { - "type": "number" - }, - "invalid_emails": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "processed": { - "type": "number" - }, - "requests": { - "type": "number" - }, - "spam_report_drops": { - "type": "number" - }, - "spam_reports": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - }, - "unsubscribe_drops": { - "type": "number" - }, - "unsubscribes": { - "type": "number" - } - } - } - } + "type": "string" } } } } - } - example: |- - [ + example: |- { - "date": "2015-10-01", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-02", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-03", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-04", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-05", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-06", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-07", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-08", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-09", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-10", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } + "recipient_emails": [ + "test1@example.com", + "test2@example.com" ] } - ] - queryParameters: - limit: - type: string - offset: - type: string - aggregated_by: - type: string - subusers: - type: string - required: true - start_date: - type: string - required: true - end_date: - type: string - /sums: - displayName: sums - description: '' - uriParameters: {} + queryParameters: {} get: - displayName: ' Gets the total sums of each email statistic metric for all subusers over the given date range.' + displayName: Get information on a single suppression group. + description: |- + **This endpoint allows you to retrieve a single suppression group.** + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. headers: {} responses: '200': @@ -567,48 +368,98 @@ documentation: schema: |- { "type": "object", - "properties": { - "date": { - "type": "string" + "allOf": [ + { + "$ref": "#/definitions/suppression_group" }, - "stats": { - "type": "array", - "items": { - "properties": {} + { + "type": "object", + "properties": { + "unsubscribes": { + "type": "integer", + "description": "The unsubscribes associated with this group." + } } } + ] + } + example: |- + { + "id": 100, + "name": "Newsletters", + "description": "Our monthly newsletter.", + "last_email_sent_at": null, + "is_default": true, + "unsubscribes": 400 + } + queryParameters: {} + patch: + displayName: Update a suppression group. + description: |- + **This endpoint allows you to update or change a suppression group.** + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + body: + application/json: + example: '' + schema: |- + { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The id of the suppression group." + }, + "name": { + "type": "string", + "description": "The name of the suppression group. Each group created by a user must have a unique name.", + "maxLength": 30 + }, + "description": { + "type": "string", + "description": "The description of the suppression group.", + "maxLength": 100 + }, + "is_default": { + "type": "boolean", + "description": "Indicates if the suppression group is set as the default group." } + }, + "required": [ + "name" + ] + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/suppression_group" } example: |- { - "date": "2015-10-11", - "stats": [] + "id": 103, + "name": "Item Suggestions", + "description": "Suggestions for items our users might like." } - queryParameters: - sort_by_direction: - type: string - start_date: - type: string - end_date: - type: string - limit: - type: string - offset: - type: string - aggregated_by: - type: string - sort_by_metric: - type: string - /reputations: - displayName: reputations - description: '' + queryParameters: {} uriParameters: {} get: - displayName: Retrieve Subuser Reputations + displayName: Retrieve all suppression groups associated with the user. description: |- - Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will effect your sender rating. + **This endpoint allows you to retrieve a list of all suppression groups created by this user.** - This endpoint allows you to request the reputations for your subusers. + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. headers: {} responses: '200': @@ -618,731 +469,239 @@ documentation: { "type": "array", "items": { - "type": "object", - "properties": { - "reputation": { - "type": "number", - "description": "The sender reputation this subuser has attained." - }, - "username": { - "type": "string", - "description": "The subuser that has this reputation.f" - } - }, - "required": [ - "reputation", - "username" - ] + "$ref": "#/definitions/suppression_group_unsubscribes" } } example: |- [ { - "username": "example_subuser", - "reputation": 99 + "id": 1234, + "name": "Unsubscribe Group", + "description": "An Unsubscribe Group", + "last_email_sent_at": null, + "is_default": true, + "unsubscribes": 1234 }, { - "username": "example_subuser2", - "reputation": 95.2 + "id": 1234, + "name": "Unsubscribe Group", + "description": "An Unsubscribe Group", + "last_email_sent_at": null, + "is_default": true, + "unsubscribes": 1234 } ] - '401': + queryParameters: {} + post: + displayName: Create a Group + description: |- + **This endoint allows you to create a new suppression group.** + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + body: + application/json: + example: |- + { + "name": "A group name", + "description": "A group description", + "is_default": false + } + schema: |- + { + "title": "Create a Group request", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the new suppression group. May not share its name with any other suppression group on the user.", + "maxLength": 30 + }, + "description": { + "type": "string", + "description": "A description of the suppression group.", + "maxLength": 100 + }, + "is_default": { + "type": "boolean", + "default": "false", + "description": "Indicates if this is the default suppression group." + } + }, + "required": [ + "name", + "description" + ] + } + headers: {} + responses: + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "$ref": "#/definitions/suppression_group" } - example: '' - queryParameters: - subuser_name: - type: string - uriParameters: {} - post: - displayName: Create Subuser - description: |- - This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. - - For more information about Subusers: - - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - body: - application/json: - example: |- - { - "username": "John@example.com", - "email": "John@example.com", - "password": "johns_password", - "ips": [ - "1.1.1.1", - "2.2.2.2" - ] - } - schema: |- - { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username for this subuser." - }, - "email": { - "type": "string", - "description": "The email address of the subuser.", - "format": "email" - }, - "password": { - "type": "string", - "description": "The password this subuser will use when logging into SendGrid." - }, - "ips": { - "type": "array", - "description": "The IP addresses that should be assigned to this subuser.", - "items": { - "type": "string", - "format": "ipv4" - } - } - }, - "required": [ - "username", - "email", - "password", - "ips" - ] - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/subuser_post" - } - example: |- - { - "username": "example_subuser", - "user_id": 1234, - "email": "example@example.com", - "signup_session_token": "", - "authorization_token": "", - "credit_allocation": { - "type": "unlimited" - } - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "username exists" - }, - { - "message": "unable to validate IPs at this time" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '403': + example: |- + { + "id": 1234, + "name": "A group name", + "description": "A group description", + "last_email_sent_at": null, + "is_default": false + } + queryParameters: {} + /suppressions: + displayName: suppressions + description: '' + /global: + displayName: global + description: '' + '/{email}': + displayName: '{email}' + description: '' + uriParameters: + email: + type: string + get: + displayName: Retrieve a Global Suppression + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "title": "Retrieve a Global Suppression response", + "type": "object", + "properties": { + "recipient_email": { + "type": "string" + } + }, + "required": [ + "recipient_email" + ] + } + example: '' + queryParameters: {} + delete: + displayName: Delete a Global Suppression + headers: {} + responses: + '204': + body: + application/json: + schema: '{}' + example: '' + queryParameters: {} + '/{email_address}': + displayName: '{email_address}' + description: '' + uriParameters: + email_address: + type: string + get: + displayName: Check if a recipient address is in the global suppressions group. + description: Global Suppressions are email addresses that will not receive any emails. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "recipient_email": { + "type": "string" + } + } + } + example: |- + { + "recipient_email": "test1@example.com" + } + queryParameters: {} + uriParameters: {} + post: + displayName: Add recipient addresses to the global suppression group. + description: Global Suppressions are email addresses that will not receive any emails. body: application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } example: |- { - "errors": [ - { - "message": "you dont have permission to access this resource" - } + "recipient_emails": [ + "test1@example.com", + "test2@example.com" ] } - '500': - body: - application/json: schema: |- { "type": "object", - "properties": {} - } - example: |- - { - "errors": [ - { - "message": "unable to validate IPs at this time" - } - ] - } - queryParameters: {} - get: - displayName: List all Subusers - description: |- - This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. - - For more information about Subusers: - - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/subuser" - } - } - example: |- - [ - { - "disabled": false, - "email": "example@example.com", - "id": 1234, - "username": "example_subuser" - }, - { - "disabled": false, - "email": "example2@example.com", - "id": 1234, - "username": "example_subuser2" - } - ] - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" + "properties": { + "recipient_emails": { + "type": "array", + "items": { + "type": "string" + } } - ] - } - description: Unexpected error in API call. See HTTP response body for details. - queryParameters: - username: - type: string - description: The username of this subuser. - limit: - type: number - description: The number of results you would like to get in each request. - offset: - type: number - description: The number of subusers to skip. - '/{subuser_name}': - displayName: '{subuser_name}' - description: '' - /ips: - displayName: ips - description: '' - uriParameters: {} - put: - displayName: Update IPs assigned to a subuser - description: "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)" - body: - application/json: - example: |- - [ - "127.0.0.1" - ] - schema: |- - { - "type": "array", - "items": { - "type": "string", - "format": "ipv4" } } headers: {} responses: - '200': + '201': body: application/json: schema: |- { "type": "object", "properties": { - "ips": { + "recipient_emails": { "type": "array", "items": { - "type": "string", - "format": "ipv4" + "type": "string" } } } } example: |- { - "ips": [ - "127.0.0.1" - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } + "recipient_emails": [ + "test1@example.com", + "test2@example.com" ] } - queryParameters: - subuser_name: - type: string - required: true + queryParameters: {} +/mailbox_providers: + displayName: mailbox_providers + description: '' + /stats: + displayName: stats + description: '' uriParameters: {} - patch: - displayName: Enable/disable a subuser + get: + displayName: Retrieve email statistics by mailbox provider. description: |- - This endpoint allows you to enable or disable a subuser. + **This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.** - For more information about Subusers: + **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. - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - body: - application/json: - example: |- - { - "disabled": false - } - schema: |- - { - "type": "object", - "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not this subuser is disabled. True means disabled, False means enabled." - } - } - } + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). headers: {} responses: - '204': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "invalid username" - }, - { - "message": "no fields provided" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '500': + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "unable to enable user" - } - ] - } - queryParameters: {} - /monitor: - displayName: monitor - description: '' - uriParameters: {} - get: - displayName: Retrieve monitor settings for a subuser - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/monitor" - } - example: |- - { - "email": "example@example.com", - "frequency": 500 - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" - } - ] - } - queryParameters: - subuser_name: - type: string - description: The name of the subuser for which to retrieve monitor settings. - delete: - displayName: Delete monitor settings - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" - } - ] - } - queryParameters: - subuser_name: - type: string - description: 'The name of the subuser from whom you would like to delete the monitor settings. ' - required: true - put: - displayName: Update Monitor Settings for a subuser - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - body: - application/json: - example: |- - { - "email": "example@example.com", - "frequency": 500 - } - schema: |- - { - "$ref": "#/definitions/monitor" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/monitor" - } - example: |- - { - "email": "example@example.com", - "frequency": 500 - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "email", - "message": "Email is required" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - post: - displayName: Create monitor settings - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - body: - application/json: - example: |- - { - "email": "example@example.com", - "frequency": 50000 - } - schema: |- - { - "$ref": "#/definitions/monitor" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/monitor" - } - example: |- - { - "email": "example@example.com", - "frequency": 50000 - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "User already has a monitor" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - delete: - displayName: Delete a subuser - description: |- - This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. - - For more information about Subusers: - - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: - subuser_name: - type: string - description: The name of the subuser. - required: true -/geo: - displayName: geo - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Gets email statistics by country and state/province. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "properties": { - "type": { - "type": "string" - }, - "name": { - "type": "string" - }, - "metrics": { - "type": "object", - "properties": { - "clicks": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - } - } - } - } - } - } - } - } + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_mailbox_provider" + } } example: |- [ @@ -1350,11 +709,17 @@ documentation: "date": "2015-10-11", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1365,11 +730,17 @@ documentation: "date": "2015-10-12", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1380,11 +751,17 @@ documentation: "date": "2015-10-13", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1395,11 +772,17 @@ documentation: "date": "2015-10-14", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1410,11 +793,17 @@ documentation: "date": "2015-10-15", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1425,11 +814,17 @@ documentation: "date": "2015-10-16", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1440,11 +835,17 @@ documentation: "date": "2015-10-17", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1455,11 +856,17 @@ documentation: "date": "2015-10-18", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1470,11 +877,17 @@ documentation: "date": "2015-10-19", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1485,11 +898,17 @@ documentation: "date": "2015-10-20", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1500,11 +919,17 @@ documentation: "date": "2015-10-21", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 1, + "drops": 0, "opens": 1, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 1 } @@ -1515,11 +940,17 @@ documentation: "date": "2015-10-22", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1530,11 +961,17 @@ documentation: "date": "2015-10-23", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1545,11 +982,17 @@ documentation: "date": "2015-10-24", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1560,11 +1003,17 @@ documentation: "date": "2015-10-25", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1575,13 +1024,19 @@ documentation: "date": "2015-10-26", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, - "opens": 0, + "deferred": 0, + "delivered": 2, + "drops": 0, + "opens": 2, + "spam_reports": 0, "unique_clicks": 0, - "unique_opens": 0 + "unique_opens": 2 } } ] @@ -1590,11 +1045,17 @@ documentation: "date": "2015-10-27", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1605,11 +1066,17 @@ documentation: "date": "2015-10-28", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1620,11 +1087,17 @@ documentation: "date": "2015-10-29", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1635,11 +1108,17 @@ documentation: "date": "2015-10-30", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1650,11 +1129,17 @@ documentation: "date": "2015-10-31", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1665,11 +1150,17 @@ documentation: "date": "2015-11-01", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1680,11 +1171,17 @@ documentation: "date": "2015-11-02", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1695,11 +1192,17 @@ documentation: "date": "2015-11-03", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1710,11 +1213,17 @@ documentation: "date": "2015-11-04", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1725,11 +1234,17 @@ documentation: "date": "2015-11-05", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1740,11 +1255,17 @@ documentation: "date": "2015-11-06", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1755,11 +1276,17 @@ documentation: "date": "2015-11-07", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1770,11 +1297,17 @@ documentation: "date": "2015-11-08", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1785,11 +1318,17 @@ documentation: "date": "2015-11-09", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1800,11 +1339,17 @@ documentation: "date": "2015-11-10", "stats": [ { - "type": "province", - "name": "TX", + "type": "mailbox_provider", + "name": "Gmail", "metrics": { + "blocks": 0, + "bounces": 0, "clicks": 0, + "deferred": 0, + "delivered": 0, + "drops": 0, "opens": 0, + "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } @@ -1814,1565 +1359,882 @@ documentation: ] queryParameters: limit: - type: string + type: integer + description: The number of results to include on each page. offset: - type: string + type: integer + description: The number of results to exclude. aggregated_by: type: string + description: 'How to group the stats. Must be either "day", "wee", or "month".' + enum: + - day + - week + - month start_date: type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true end_date: type: string - country: + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + mailbox_providers: type: string -/mail_settings: - displayName: mail_settings + description: The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times. +/contactdb: + displayName: contactdb description: '' - /bounce_purge: - displayName: bounce_purge + /lists: + displayName: lists description: '' - uriParameters: {} - get: - displayName: Get bounce purge mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_bounce_purge" - } - example: |- - { - "enabled": false, - "soft_bounces": 1234, - "hard_bounces": null - } - queryParameters: {} - patch: - displayName: Update bounce purge mail settings - body: - application/json: - example: |- - { - "enabled": true, - "hard_bounces": 5, - "soft_bounces": 5 - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "hard_bounces": { - "type": "integer" - }, - "soft_bounces": { - "type": "integer" + '/{list_id}': + displayName: '{list_id}' + description: '' + /recipients: + displayName: recipients + description: '' + uriParameters: {} + get: + displayName: List Recipients on a List + description: |- + List all the recipients currently on a specific list. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "recipients": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_recipient" + } + } + } } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_bounce_purge" - } - example: |- - { - "enabled": false, - "hard_bounces": null, - "soft_bounces": null - } - queryParameters: {} - /forward_bounce: - displayName: forward_bounce - description: '' - uriParameters: {} - get: - displayName: Get forward bounce mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_bounce" - } - example: |- - { - "enabled": false, - "email": null - } - queryParameters: {} - patch: - displayName: Update forward bounce mail settings - body: - application/json: - example: |- - { - "enabled": true, - "email": "example@example.com" - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "email": { - "type": "string" + example: |- + { + "recipients": [ + { + "created_at": 1433348344, + "custom_fields": [ + { + "id": 6234, + "name": "age", + "type": "number", + "value": null + }, + { + "id": 6233, + "name": "country", + "type": "text", + "value": null + }, + { + "id": 6235, + "name": "fname", + "type": "text", + "value": "Example" + }, + { + "id": 6239, + "name": "lname", + "type": "text", + "value": "User" + }, + { + "id": 6240, + "name": "lname", + "type": "text", + "value": null + } + ], + "email": "example@example.com", + "first_name": "Example", + "id": "ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==", + "last_clicked": 1438616117, + "last_emailed": 1438613272, + "last_name": "User", + "last_opened": 1438616109, + "updated_at": 1438616119 + } + ] } - } - } - headers: {} - responses: - '200': + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is not a valid integer" + }, + { + "field": "page", + "message": "Returned if page is not a valid integer" + }, + { + "field": "page", + "message": "Returned if page is less than 1" + }, + { + "field": "page_size", + "message": "Returned if page_size is not a valid integer" + }, + { + "field": "page_size", + "message": "Returned if page_size is less than 1 or greater than 1000" + } + ] + } + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" + '404': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: |- + { + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is invalid" + } + ] + } + description: '"list_id" : "Returned if list_id does not exist"' + queryParameters: + page: + type: integer + description: Page index of first recipient to return (must be a positive integer) + page_size: + type: integer + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) + list_id: + type: number + description: The ID of the list whose recipients you are requesting. + required: true + post: + displayName: Add Multiple Recipients to a List + description: |- + Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). body: application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_bounce" - } example: |- - { - "email": "", - "enabled": true - } - queryParameters: {} - /bcc: - displayName: bcc - description: '' - uriParameters: {} - patch: - displayName: Update BCC mail settings - body: - application/json: - example: |- - { - "enabled": false - } - schema: |- - { - "$ref": "#/definitions/mail_settings::patch" - } - headers: {} - responses: - '200': - body: - application/json: + [ + "recipient_id1", + "recipient_id2" + ] schema: |- { - "type": "object", - "properties": { - "email": { - "type": "string" - }, - "enabled": { - "type": "boolean" - } + "type": "array", + "items": { + "type": "string" } } - example: |- - { - "email": "example@example.com", - "enabled": false - } - queryParameters: {} - get: - displayName: Get BCC mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_bcc" - } - example: |- - { - "email": "example@example.com", - "enabled": false - } - queryParameters: {} - /address_whitelist: - displayName: address_whitelist - description: '' - uriParameters: {} - patch: - displayName: Update address whitelist mail settings - body: - application/json: - example: |- - { - "enabled": true, - "list": [ - "email1@example.com", - "example.com" - ] - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "list": { - "type": "array", - "items": { - "type": "string" - } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "type": "null" } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_bounce_purge" - } - example: |- - { - "enabled": false, - "list": [ - "example.com" - ] - } - queryParameters: {} - get: - displayName: Get address whitelist mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_address_whitelabel" - } - example: |- - { - "enabled": false, - "list": [ - "example.com" - ] - } - queryParameters: {} - /forward_spam: - displayName: forward_spam - description: '' - uriParameters: {} - get: - displayName: Get forward spam mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_spam" - } - example: |- - { - "email": "", - "enabled": true - } - queryParameters: {} - patch: - displayName: Update forward spam mail settings - body: - application/json: - example: |- - { - "email": "", - "enabled": false - } - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_spam" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_spam" - } - example: |- - { - "email": "", - "enabled": false - } - queryParameters: {} - /spam_check: - displayName: spam_check - description: '' - uriParameters: {} - get: - displayName: Get spam check mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_spam_check" - } - example: |- - { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } - queryParameters: {} - patch: - displayName: Update spam check mail settings - body: - application/json: - example: |- - { - "enabled": true, - "url": "url", - "max_score": 5 - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "url": { - "type": "string" - }, - "max_score": { - "type": "integer" + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_spam_check" - } - example: |- - { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } - queryParameters: {} - uriParameters: {} - get: - displayName: Get all mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string" - }, - "enabled": { - "type": "boolean" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - } - } - } - } - } - } - example: |- - { - "result": [ - { - "title": "Address Whitelist", - "enabled": false, - "name": "address_whitelist", - "description": "Address / domains that should never have email suppressed." - }, - { - "title": "BCC", - "enabled": false, - "name": "bcc", - "description": "Automatically BCC an address for every e-mail sent." - }, - { - "title": "Bounce Purge", - "enabled": false, - "name": "bounce_purge", - "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days." - }, - { - "title": "Event Notification", - "enabled": true, - "name": "event_notify", - "description": "Controls notifications for events, such as bounces, clicks, and opens." - }, - { - "title": "Footer", - "enabled": false, - "name": "footer", - "description": "Allows you to add a custom footer to outgoing email." - }, - { - "title": "Forward Bounce", - "enabled": true, - "name": "forward_bounce", - "description": "Allows you to forward bounces to a specific email address." - }, - { - "title": "Forward Spam", - "enabled": false, - "name": "forward_spam", - "description": "Allows for a copy of spam reports to be forwarded to an email address." - }, - { - "title": "Legacy Email Template", - "enabled": true, - "name": "template", - "description": "Allows you to customize your outgoing HTML emails." - }, - { - "title": "Plain Content", - "enabled": false, - "name": "plain_content", - "description": "Convert your plain text emails to HTML." - }, - { - "title": "Spam Checker", - "enabled": true, - "name": "spam_check", - "description": "Check outbound messages for spam content." - } - ] - } - queryParameters: - limit: - type: string - offset: - type: string - /footer: - displayName: footer - description: '' - uriParameters: {} - patch: - displayName: Update footer mail settings - body: - application/json: - example: |- - { - "enabled": true, - "html_content": "...", - "plain_content": "..." - } - schema: |- - { - "$ref": "#/definitions/mail_settings::patch" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_footer" - } - example: |- - { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - } - queryParameters: {} - get: - displayName: 'Get footer mail settings [params can be null?]' - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_footer" - } - example: |- - { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - } - queryParameters: {} - /template: - displayName: template - description: '' - uriParameters: {} - patch: - displayName: Update template mail settings - body: - application/json: - example: |- - { - "enabled": true, - "html_content": "<% body %>" - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" + example: |- + { + "errors": [ + { + "field": "list_id", + "message": "list_id is invalid" + }, + { + "field": "recipient_id", + "message": "no valid recipients were provided" + }, + { + "field": null, + "message": "no recipients were added" + }, + { + "field": null, + "message": "request body is invalid JSON" + } + ] } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "" : "Returned if no valid recipient ids were passed" + "" : "Returned if no recipients were added" + "" : "Returned if request body is invalid JSON" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } - } - example: "{\n \"enabled\": false,\n \"html_content\": \"

<% body %>Example

\\n\"\n}" - queryParameters: {} - get: - displayName: Get template mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } - } - example: "{\n \"enabled\": false,\n \"html_content\": \"

<% body %>Example

\\n\"\n}" - queryParameters: {} - /plain_content: - displayName: plain_content - description: '' - uriParameters: {} - patch: - displayName: Update plain content mail settings - body: - application/json: - example: |- - { - "enabled": false - } - schema: |- - { - "$ref": "#/definitions/mail_settings::patch" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings::patch" - } - example: |- - { - "enabled": false - } - queryParameters: {} - get: - displayName: Get plain content mail settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings::patch" - } - example: |- - { - "enabled": false - } - queryParameters: {} -/scopes: - displayName: scopes - description: '' - uriParameters: {} - get: - displayName: A list of scopes for which that user has access. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "items": { - "properties": {} - } - } - } - } - example: |- - { - "scopes": [ - "alerts.create", - "alerts.read", - "alerts.update", - "alerts.delete", - "asm.groups.create", - "asm.groups.read", - "asm.groups.update", - "asm.groups.delete", - "asm.groups.suppressions.create", - "asm.groups.suppressions.read", - "asm.groups.suppressions.delete", - "asm.suppressions.global.create", - "asm.suppressions.global.read", - "asm.suppressions.global.delete", - "billing.create", - "billing.read", - "billing.update", - "billing.delete", - "ui.confirm_email", - "signup.trigger_confirmation", - "ui.provision", - "ips.warmup.create", - "ips.warmup.read", - "ips.warmup.delete", - "ips.pools.create", - "ips.pools.read", - "ips.pools.update", - "ips.pools.delete", - "ips.pools.ips.create", - "ips.pools.ips.delete", - "ips.assigned.read", - "ips.read", - "mail.send", - "mail_settings.read", - "mail_settings.bcc.read", - "mail_settings.bcc.update", - "mail_settings.address_whitelist.read", - "mail_settings.address_whitelist.update", - "mail_settings.footer.read", - "mail_settings.footer.update", - "mail_settings.forward_spam.read", - "mail_settings.forward_spam.update", - "mail_settings.plain_content.read", - "mail_settings.plain_content.update", - "mail_settings.spam_check.read", - "mail_settings.spam_check.update", - "mail_settings.bounce_purge.read", - "mail_settings.bounce_purge.update", - "mail_settings.forward_bounce.read", - "mail_settings.forward_bounce.update", - "partner_settings.read", - "partner_settings.new_relic.read", - "partner_settings.new_relic.update", - "partner_settings.sendwithus.read", - "partner_settings.sendwithus.update", - "tracking_settings.read", - "tracking_settings.click.read", - "tracking_settings.click.update", - "tracking_settings.subscription.read", - "tracking_settings.subscription.update", - "tracking_settings.open.read", - "tracking_settings.open.update", - "tracking_settings.google_analytics.read", - "tracking_settings.google_analytics.update", - "user.webhooks.event.settings.read", - "user.webhooks.event.settings.update", - "user.webhooks.event.test.create", - "user.webhooks.parse.settings.create", - "user.webhooks.parse.settings.read", - "user.webhooks.parse.settings.update", - "user.webhooks.parse.settings.delete", - "stats.read", - "stats.global.read", - "categories.stats.read", - "categories.stats.sums.read", - "devices.stats.read", - "clients.stats.read", - "clients.phone.stats.read", - "clients.tablet.stats.read", - "clients.webmail.stats.read", - "clients.desktop.stats.read", - "geo.stats.read", - "mailbox_providers.stats.read", - "browsers.stats.read", - "subusers.stats.read", - "subusers.stats.sums.read", - "subusers.stats.monthly.read", - "user.webhooks.parse.stats.read", - "subusers.create", - "subusers.read", - "subusers.update", - "subusers.delete", - "subusers.monitor.create", - "subusers.monitor.read", - "subusers.monitor.update", - "subusers.monitor.delete", - "subusers.credits.read", - "subusers.credits.update", - "subusers.credits.remaining.update", - "subusers.reputations.read", - "subusers.summary.read", - "suppression.bounces.read", - "suppression.bounces.delete", - "suppression.blocks.read", - "suppression.blocks.delete", - "suppression.invalid_emails.read", - "suppression.invalid_emails.delete", - "suppression.spam_reports.read", - "suppression.spam_reports.delete", - "suppression.unsubscribes.create", - "suppression.unsubscribes.read", - "suppression.unsubscribes.delete", - "templates.create", - "templates.read", - "templates.update", - "templates.delete", - "templates.versions.create", - "templates.versions.read", - "templates.versions.update", - "templates.versions.delete", - "templates.versions.activate.create", - "user.account.read", - "user.credits.read", - "user.email.create", - "user.email.read", - "user.email.update", - "user.email.delete", - "user.profile.create", - "user.profile.read", - "user.profile.update", - "user.profile.delete", - "user.password.update", - "user.timezone.read", - "user.timezone.update", - "user.username.read", - "user.username.update", - "user.settings.enforced_tls.read", - "user.settings.enforced_tls.update", - "api_keys.create", - "api_keys.read", - "api_keys.update", - "api_keys.delete", - "email_activity.read", - "credentials.create", - "credentials.read", - "credentials.update", - "credentials.delete", - "categories.create", - "categories.read", - "categories.update", - "categories.delete", - "mail_settings.template.read", - "mail_settings.template.update", - "user.multifactor_authentication.create", - "user.multifactor_authentication.read", - "user.multifactor_authentication.update", - "user.multifactor_authentication.delete", - "admin.impersonate", - "newsletter.create", - "newsletter.read", - "newsletter.update", - "newsletter.delete", - "marketing_campaigns.create", - "marketing_campaigns.read", - "marketing_campaigns.update", - "marketing_campaigns.delete", - "ui.signup_complete", - "mail.batch.create", - "mail.batch.read", - "mail.batch.update", - "mail.batch.delete", - "user.scheduled_sends.create", - "user.scheduled_sends.read", - "user.scheduled_sends.update", - "user.scheduled_sends.delete", - "access_settings.whitelist.create", - "access_settings.whitelist.read", - "access_settings.whitelist.update", - "access_settings.whitelist.delete" - ] - } - queryParameters: {} -/whitelabel: - displayName: whitelabel - description: '' - /domains: - displayName: domains - description: '' - '/{domain_id}': - displayName: '{domain_id}' - description: '' - uriParameters: {} - delete: - displayName: Delete a domain whitelabel. - description: |- - **This endpoint allows you to delete a domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | The ID of the domain whose whitelabel you want to delete. | - headers: {} - responses: - '204': - body: - application/json: - schema: '{}' - example: '' - queryParameters: {} - get: - displayName: Retrieve a domain whitelabel. - description: |- - **This endpoint allows you to retrieve a specific domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | The ID of the whitelabeled domain. | - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/whitelabel::domain" - } - example: '' - queryParameters: - id: - type: integer - description: "The ID of the domain you're whitelabeling." - required: true - patch: - displayName: Update a domain whitelabel. - description: |- - **This endpoint allows you to update the settings for a domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | The ID of the domain you're whitelabeling. | - body: - application/json: - example: |- - { - "default": false, - "custom_spf": true - } - schema: |- - { - "type": "object", - "properties": { - "default": { - "type": "boolean", - "default": "false", - "description": "Indicates whether this domain whitelabel should be considered the default." - }, - "custom_spf": { - "type": "boolean", - "default": "false", - "description": "Indicates whether to generate a custom SPF record for manual security." - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "Update a Domain response", - "type": "object", - "properties": { - "default false": { - "description": "Inidcates whether this domain whitelabel should be considered the default. Defaults to false.", - "type": "boolean" - }, - "custom_spf false": { - "description": "Indicates whether to generate a custom SPF record for manual security. Defaults to false.", - "type": "boolean" - } - } - } - example: '' - queryParameters: {} - /subuser: - displayName: subuser - description: '' - uriParameters: {} - post: - displayName: Associate a domain whitelabel with a given user. - description: |- - **This endpoint allows you to associate a specific domain whitelabel with a subuser.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | domain_id | integer | ID of the domain whitelabel to associate with the subuser. | - body: - application/json: - example: |- - { - "username": "jane@example.com" - } - schema: |- - { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Username to associate with the domain whitelabel." - } - }, - "required": [ - "username" - ] - } - headers: {} - responses: - '201': + '404': body: application/json: schema: |- { - "$ref": "#/definitions/whitelabel:domain_spf" + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false + "errors": [ + { + "field": "list_id", + "message": "list_id does not exist" }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false + { + "field": "recipient_id", + "message": "recipient_id does not exist" } - } + ] } - queryParameters: {} - '/{id}': - displayName: '{id}' - description: '' - /validate: - displayName: validate - description: '' - uriParameters: {} - post: - displayName: Validate a domain whitelabel. - description: |- - **This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + description: '"list_id": "Returned if list_id does not exist"' + queryParameters: + list_id: + type: number + description: 'The list to add your recipients to. ' + required: true + '/{recipient_id}': + displayName: '{recipient_id}' + description: '' + uriParameters: + recipient_id: + type: string + delete: + displayName: Delete a Single Recipient from a Single List + description: |- + Delete a single recipient from a list. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer |ID of the domain whitelabel to validate. | - body: {} - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the domain whitelabel." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "validation_resuts": { - "type": "object", - "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", - "properties": { - "mail_cname": { - "type": "object", - "description": "The CNAME record for the domain whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this DNS record is valid." - }, - "reason": { - "type": "string", - "description": "The reason this record is invalid." - } - } - }, - "dkim1": { - "type": "object", - "description": "A DNS record for this domain whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid." - }, - "reason": { - "type": "null" - } - } - }, - "dkim2": { - "type": "object", - "description": "A DNS record for this whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid." - }, - "reason": { - "type": "null" - } - } - }, - "spf": { - "type": "object", - "description": "The SPF record for the whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - }, - "reason": { - "type": "null" - } - } - } - } - } - } - } - example: "{\n \"id\": 1,\n \"valid\": true,\n \"validation_resuts\": {\n \"mail_cname\": {\n \"valid\": false,\n \"reason\": \"Expected your MX record to be \\\"mx.sendgrid.net\\\" but found \\\"example.com\\\".\"\n },\n \"dkim1\": {\n \"valid\": true,\n \"reason\": null\n },\n \"dkim2\": {\n \"valid\": true,\n \"reason\": null\n },\n \"spf\": {\n \"valid\": true,\n \"reason\": null\n }\n }\n}" - '400': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - description: Unexpected error in API call. See HTTP response body for details. - '500': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message explaining the reason for the error." - } - }, - "required": [ - "message" - ] - } - } - } - } - example: |- - { - "errors": [ - { - "message": "internal error getting TXT" - } - ] - } - queryParameters: {} - /ips: - displayName: ips - description: '' - uriParameters: {} - post: - displayName: Add an IP to a domain whitelabel. - description: |- - **This endpoint allows you to add an IP address to a domain whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | ID of the domain to which you are adding an IP | - body: - application/json: - example: |- - { - "ip": "192.168.0.1" - } - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." - } - }, - "required": [ - "ip" - ] - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/whitelabel:domain_spf" - } - example: |- - { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - queryParameters: {} - '/{ip}': - displayName: '{ip}' - description: '' - uriParameters: {} - delete: - displayName: Remove an IP from a domain whitelabel. - description: |- - **This endpoint allows you to remove a domain's IP address from that domain's whitelabel.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | ID of the domain whitelabel to delete the IP from. | - | ip | string | IP to remove from the domain whitelabel. | + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '200': + '204': body: application/json: schema: |- { - "$ref": "#/definitions/whitelabel:domain_spf" + "type": "null" + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is invalid" }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false + { + "field": "recipient_id", + "message": "no valid recipients were provided" } - } + ] } - queryParameters: {} - /subuser: - displayName: subuser - description: '' - uriParameters: {} - delete: - displayName: Disassociate a domain whitelabel from a given user. - description: |- - **This endpoint allows you to disassociate a specific whitelabel from a subuser.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - | username | string | required | Username for the subuser to find associated whitelabels for. | - headers: {} - responses: - '204': + description: |- + "list_id" : "Returned if list_id is not valid" + "recipient_id" : "Returned if recipient_id is not valid" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id does not exist" + }, + { + "field": "recipient_id", + "message": "Returned if recipient_id does not exist" + } + ] + } + description: |- + "list_id" : "Returned if list_id does not exist" + "recipient_id" : "Returned if recipient_id does not exist" + queryParameters: + list_id: + type: number + description: The ID of the list you are taking this recipient away from. + required: true + recipient_id: + type: number + description: The ID of the recipient to take off the list. + required: true + post: + displayName: Add a Single Recipient to a List + description: |- + Add a recipient to a list. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). body: application/json: - schema: '{}' example: '' - queryParameters: {} - get: - displayName: List the domain whitelabel associated with the given user. + schema: |- + { + "type": "null" + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "type": "null" + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is invalid" + }, + { + "field": "recipient_id", + "message": "Returned if recipient_id is invalid" + } + ] + } + description: |- + "list_id" : "Returned if list_id is invalid" + "recipient_id" : "Returned if recipient_id is invalid" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id does not exist" + }, + { + "field": "recipient_id", + "message": "Returned if recipient_id does not exist" + } + ] + } + description: |- + "list_id" : "Returned if list_id does not exist" + "recipient_id" : "Returned if recipient_id does not exist" + queryParameters: + list_id: + type: number + description: The ID of the list to add the recipient to. + recipient_id: + type: string + description: The recipient you are adding to the list indicated. + uriParameters: + list_id: + type: string + delete: + displayName: Delete a List description: |- - **This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + Delete a list by ID. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | username | string | Username of the subuser to find associated whitelabels for. | + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '200': + '202': body: application/json: schema: |- { - "$ref": "#/definitions/whitelabel:domain_spf" + "type": "null" + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false + "errors": [ + { + "field": "delete_contacts", + "message": "delete_contacts not a bool" }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false + { + "field": "list_id", + "message": "Returned if list_id is not valid" } - } + ] } - queryParameters: {} - uriParameters: {} - post: - displayName: Create a domain whitelabel. - description: |- - **This endpoint allows you to create a whitelabel for one of your domains.** - - If you are creating a domain whitelabel that you would like a subuser to use, you have two options: - 1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. - 2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - body: - application/json: - example: |- - { - "domain": "example.com", - "subdomain": "news", - "username": "john@example.com", - "ips": [ - "192.168.1.1", - "192.168.1.2" - ], - "custom_spf": true, - "default": true, - "automatic_security": false - } - schema: |- - { - "type": "object", - "properties": { - "domain": { - "type": "string", - "description": "Domain being whitelabeled." - }, - "subdomain": { - "type": "string", - "description": "The subdomain to use for this domain whitelabel." - }, - "username": { - "type": "string", - "description": "The username that this whitelabel will be associated with." - }, - "ips": { - "type": "array", - "description": "The IP addresses that will be included in the custom SPF record for this whitelabel.", - "items": { - "type": "string" - } - }, - "custom_spf": { - "type": "boolean", - "description": "Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security." - }, - "default": { - "type": "boolean", - "description": "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain." - }, - "automatic_security": { - "type": "boolean", - "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation." - } - }, - "required": [ - "domain", - "subdomain" - ] - } + description: |- + "list_id" : "Returned if list_id is not valid" + "delete_contacts" : "Returned if delete_contacts is not valid" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "List not found: 5" + } + ] + } + description: '"list_id" : "Returned if list_id does not exist"' + queryParameters: + delete_contacts: + type: boolean + description: Adds the ability to delete all contacts on the list in addition to deleting the list. + patch: + displayName: Update a List + description: |- + Update the name of a list. + + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + body: + application/json: + example: |- + { + "name": "newlistname" + } + schema: |- + { + "title": "Update a List request", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The new name for your list. " + } + }, + "required": [ + "name" + ] + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "invalid id" + } + ] + } + description: |- + "name" : "Returned if list name is a duplicate of existing list or segment" + "name" : "Returned if list name is invalid or not provided" + "list_id" : "Returned if list_id is not valid" + "" : "Returned if request body is invalid JSON" + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "List ID does not exist" + } + ] + } + description: '"list_id" : "Returned if list_id does not exist"' + queryParameters: + list_id: + type: number + description: The ID of the list you are updating. + required: true + get: + displayName: Get a single list. + description: "Get a single list. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/contactdb_list" + } + example: |- + { + "id": 1, + "name": "listname", + "recipient_count": 0 + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "invalid id" + } + ] + } + description: '"list_id" : "Returned if list_id is not valid"' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "List ID does not exist" + } + ] + } + description: '"list_id" : "Returned if list_id does not exist"' + queryParameters: + list_id: + type: number + description: The ID of the list to retrieve. + uriParameters: {} + delete: + displayName: Delete Multiple lists + description: |- + Delete multiple lists. + + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '201': + '204': body: application/json: schema: |- { - "$ref": "#/definitions/whitelabel::domain" + "type": "null" + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 302183, - "user_id": 1446226, - "subdomain": "example", - "domain": "example.com", - "username": "mbernier", - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_cname": { - "valid": false, - "type": "cname", - "host": "example.example.com", - "data": "u1446226.wl.sendgrid.net" + "errors": [ + { + "field": null, + "message": "list id was invalid" + } + ] + } + description: '"id" : "Returned if all list ids are not valid"' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + post: + displayName: Create a List + description: |- + Create a list for your recipients. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + body: + application/json: + example: |- + { + "name": "your list name" + } + schema: |- + { + "title": "Create a List request", + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": [ + "name" + ] + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/contactdb_list" + } + example: |- + { + "id": 1, + "name": "your list name", + "recipient_count": 0 + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "Returned if request body is invalid JSON" }, - "dkim1": { - "valid": false, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1.domainkey.u1446226.wl.sendgrid.net" + { + "field": "name", + "message": "Returned if list name is not a string" }, - "dkim2": { - "valid": false, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2.domainkey.u1446226.wl.sendgrid.net" + { + "field": "name", + "message": "Returned if list name is a duplicate of an existing list or segment" } - } + ] + } + description: |- + "name" : "Returned if list name is a duplicate of an existing list or segment" + "name" : "Returned if list name is not a string" + "" : "Returned if request body is invalid JSON" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } queryParameters: {} get: - displayName: List all domain whitelabels. - description: | - **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** + displayName: List All Lists + description: |- + Returns an empty list if you GET and no lists exist on your account. - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "title": "List All Lists response", + "type": "object", + "properties": { + "lists": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_list" + } + } + }, + "required": [ + "lists" + ] + } + example: |- + { + "lists": [ + { + "id": 1, + "name": "the jones", + "recipient_count": 1 + } + ] + } + queryParameters: {} + /segments: + displayName: segments + description: '' + uriParameters: {} + get: + displayName: List All Segments + description: |- + Get all your segments. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: '200': @@ -3380,373 +2242,247 @@ documentation: application/json: schema: |- { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the domain whitelabel." - }, - "user_id": { - "type": "number", - "description": "The ID of the user that this whitelabel will be associated with." - }, - "subdomain": { - "type": "string", - "description": "The subdomain created for this domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel was created for." - }, - "username": { - "type": "string", - "description": "The username that this whitelabel is associated with." - }, - "ips": { - "type": "array", - "description": "The IPs that will be included in the custom SPF record.", - "items": { - "type": "string" + "title": "List All Segments response", + "type": "object", + "properties": { + "segments": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_segments" + } + } + }, + "required": [ + "segments" + ] + } + example: |- + { + "segments": [ + { + "id": 1234, + "name": "Age segments < 25", + "conditions": [ + { + "field": "age", + "value": "25", + "operator": "lt" } - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates if this whitelabel has custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this whitelabel has been set as the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this is whitelabel was created with the legacy whitelabel tool." - }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel or not." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel that are used for authenticating the sending domain.", - "properties": { - "mail_server": { - "type": "object", - "description": "Designates which mail server is responsible for accepting messages from a domain.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record with no conflicts." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain sending the messages." - }, - "data": { - "type": "string", - "description": "The mail server responsible for accepting messages." - } - } - }, - "subdomain_spf": { - "type": "object", - "description": "The SPF record for the subdomain used to create this whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "host": { - "type": "string", - "description": "The domain that this SPF record will be used to authenticate." - }, - "data": { - "type": "string", - "description": "The SPF record." - } - } - }, - "dkim": { - "type": "object", - "description": "The DNS record used when creating the DKIM signature.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this DNS record is valid." - }, - "type": { - "type": "string", - "description": "The type of DNS record.", - "enum": [ - "cname", - "mx", - "txt" - ] - }, - "host": { - "type": "string", - "description": "The domain that these DNS records will be applied to.", - "format": "hostname" - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } - } - } - } + ], + "recipient_count": 8 }, - "required": [ - "id", - "user_id", - "subdomain", - "domain", - "username", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ] - } + { + "id": 2345, + "name": "email address - gmail", + "conditions": [ + { + "field": "email", + "value": "@gmail.com", + "operator": "contains" + } + ], + "recipient_count": 0 + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- - [ - { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "ips": [ - "192.168.1.1", - "192.168.1.2" - ], - "custom_spf": true, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": true, - "dns": { - "mail_cname": { - "host": "mail.example.com", - "type": "cname", - "data": "u7.wl.sendgrid.net", - "valid": true - }, - "spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:u7.wl.sendgrid.net -all", - "valid": true - }, - "dkim1": { - "host": "s1._domainkey.example.com", - "type": "cname", - "data": "s1._domainkey.u7.wl.sendgrid.net", - "valid": true - }, - "dkim2": { - "host": "s2._domainkey.example.com", - "type": "cname", - "data": "s2._domainkey.u7.wl.sendgrid.net", - "valid": true - } - } - }, - { - "id": 2, - "domain": "example2.com", - "subdomain": "news", - "username": "jane@example2.com", - "user_id": 8, - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_server": { - "host": "news.example2.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "news.example2.com", - "type": "txt", - "data": "v=spf1 include:sendgrid.net ~all", - "valid": false - }, - "domain_spf": { - "host": "example2.com", - "type": "txt", - "data": "v=spf1 include:news.example2.com -all", - "valid": false - }, - "dkim": { - "host": "example2.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } + { + "errors": [ + { + "field": null, + "message": "authorization required" } - } - ] - queryParameters: - limit: - type: integer - description: Number of domains to return. - offset: - type: integer - description: Paging offset. - exclude_subusers: - type: boolean - description: Exclude subuser domains from the result. - username: - type: string - description: The username associated with a whitelabel. - domain: - type: string - description: Search for domain whitelabels that match the given domain. - /default: - displayName: default + ] + } + queryParameters: {} + '/{segment_id}': + displayName: '{segment_id}' description: '' - uriParameters: {} - get: - displayName: Get the default domain whitelabel. + uriParameters: + segment_id: + type: string + delete: + displayName: Delete a Segment description: |- - **This endpoint allows you to retrieve the default whitelabel for a domain.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | domain | string |The domain to find a default domain whitelabel for. | + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '200': + '204': body: application/json: schema: |- { - "$ref": "#/definitions/whitelabel:domain_spf" + "type": "null" } example: '' - queryParameters: {} - /links: - displayName: links - description: '' - '/{id}': - displayName: '{id}' - description: '' - uriParameters: {} - delete: - displayName: Delete a Link - headers: {} - responses: - '204': + '400': body: application/json: - schema: '{}' - example: '' - queryParameters: {} - /validate: - displayName: validate - description: '' - uriParameters: {} - post: - displayName: Validate a Link - body: {} - headers: {} - responses: - '200': + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "segment_id", + "message": "Returned if segment_id is not valid" + }, + { + "field": "delete_contacts", + "message": "Returned if delete_contacts is not a valid boolean" + } + ] + } + description: |- + "segment_id" : "Returned if segment_id is not valid" + "delete_contacts" : "Returned if delete_contacts is not a valid boolean" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "segment_id", + "message": "segment_id does not exist" + } + ] + } + description: '"segment_id" : "Returned if segment_id does not exist"' + queryParameters: + delete_contacts: + type: boolean + description: True to delete all contacts matching the segment in addition to deleting the segment + /recipients: + displayName: recipients + description: '' + uriParameters: {} + get: + displayName: List Recipients On a Segment + description: |- + List all of the recipients in a segment. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + headers: {} + responses: + '200': body: application/json: schema: |- { + "title": "List Recipients On a Segment response", "type": "object", "properties": { - "id": { - "type": "integer" - }, - "valid": { - "type": "boolean" - }, - "validation_results": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "reason": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "reason": { - "type": "null" - } - } - } + "recipients": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_recipient" } } - } + }, + "required": [ + "recipients" + ] + } + example: |- + { + "recipients": [ + { + "created_at": 1422313607, + "email": "jones@example.com", + "first_name": null, + "id": "YUBh", + "last_clicked": null, + "last_emailed": null, + "last_name": "Jones", + "last_opened": null, + "updated_at": 1422313790, + "custom_fields": [ + { + "id": 23, + "name": "pet", + "value": "Indiana", + "type": "text" + } + ] + } + ] } - example: "{\n \"id\": 1,\n \"valid\": true,\n \"validation_results\": {\n \"domain_cname\": {\n \"valid\": false,\n \"reason\": \"Expected CNAME to match \\\"sendgrid.net.\\\" but found \\\"example.com.\\\".\"\n },\n \"owner_cname\": {\n \"valid\": true,\n \"reason\": null\n }\n }\n}" '400': body: application/json: schema: '{}' example: '' - description: Unexpected error in API call. See HTTP response body for details. - queryParameters: {} - patch: - displayName: Update a Link - body: - application/json: - example: |- - { - "default": true - } - schema: |- - { - "type": "object", - "properties": { - "default": { - "type": "boolean" - } - } - } + description: |- + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: '{}' + example: '' + description: |- + "segment_id" : "Returned if segment_id is not valid" + "segment_id" : "Returned if segment_id does not exist" + queryParameters: + page: + type: integer + page_size: + type: integer + get: + displayName: Retrieve a Segment + description: |- + Get a single segment by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: '200': @@ -3754,739 +2490,391 @@ documentation: application/json: schema: |- { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "domain": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "username": { - "type": "string" - }, - "user_id": { - "type": "integer" - }, - "default": { - "type": "boolean" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "dns": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } - } - } - } + "$ref": "#/definitions/contactdb_segments" } example: |- { "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": true, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" + "name": "Last Name Miller", + "list_id": 4, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" } - } + ], + "recipient_count": 1 } - queryParameters: {} - get: - displayName: Retrieve a Link - headers: {} - responses: - '200': + '400': body: application/json: schema: |- { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "domain": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "username": { - "type": "string" - }, - "user_id": { - "type": "integer" - }, - "default": { - "type": "boolean" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "dns": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } - } - } - } + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" + "errors": [ + { + "message": "if segment_id is not valid" } - } + ] } - queryParameters: {} - /default: - displayName: default - description: '' - uriParameters: {} - get: - displayName: Default Link - description: |- - Default link is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: - - headers: {} - responses: - '200': + description: '"segment_id" : "Returned if segment_id is not valid"' + '401': body: application/json: schema: |- { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "domain": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "username": { - "type": "string" - }, - "user_id": { - "type": "integer" - }, - "default": { - "type": "boolean" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "dns": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } - } + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" } - } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" + "errors": [ + { + "message": "segment_id not found" } - } + ] } + description: '"segment_id" : "Returned if segment_id does not exist"' queryParameters: - domain: - type: string - /subuser: - displayName: subuser - description: '' - uriParameters: {} - delete: - displayName: Disassociate Link + segment_id: + type: number + description: The ID of the segment you want to request. + required: true + patch: + displayName: Update a segment description: |- - Link Whitelabels can be associated with subusers via parent accounts. This functionality allows - subusers to send mail off their parent's Whitelabels. To associate a Whitelabel, the parent account - must first create a Whitelabel and validate it. Then the parent may associate the Whitelabel in - subuser management. + Update a segment. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + body: + application/json: + example: |- + { + "name": "The Millers", + "list_id": 5, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" + } + ] + } + schema: |- + { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "list_id": { + "type": "number", + "description": "The list ID you would like this segment to be built from." + }, + "conditions": { + "type": "array", + "description": "The conditions by which this segment should be created.", + "items": { + "$ref": "#/definitions/contactdb_segments_conditions" + } + } + }, + "required": [ + "name" + ] + } headers: {} responses: - '204': + '200': body: application/json: - schema: '{}' - example: '' - queryParameters: - username: - type: string - get: - displayName: List Associated Link - headers: {} - responses: - '200': + schema: |- + { + "$ref": "#/definitions/contactdb_segments" + } + example: |- + { + "id": 5, + "name": "The Millers", + "list_id": 5, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" + } + ], + "recipient_count": 1 + } + '400': body: application/json: schema: |- { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "domain": { - "type": "string" + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "request body is not valid json" }, - "subdomain": { - "type": "string" + { + "message": "invalid value is passed into one of the request body parameters" }, - "username": { - "type": "string" + { + "segment_id": "segment_id", + "message": "segment id is not valid" }, - "user_id": { - "type": "integer" + { + "field": "field", + "message": "field and set value is not passed into the request body" }, - "default": { - "type": "boolean" + { + "field": "value", + "message": "value and set value is not passed into the request body" }, - "valid": { - "type": "boolean" + { + "field": "operator", + "message": "operator and set value is not passed into the request body" }, - "legacy": { - "type": "boolean" + { + "field": "and_or", + "message": "and_or is not set on more than one condition and less than all conditions" }, - "dns": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } - } + { + "field": "and_or", + "message": "and_or is set on all conditions" + }, + { + "field": "and_or", + "message": "and_or is set on the only condition passed" + }, + { + "field": "and_or", + "message": "and_or and set value is not passed into the request body" + }, + { + "field": "list_id", + "message": "the list_id is not valid" + }, + { + "field": "name", + "message": "the name is not valid" } - } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" + "errors": [ + { + "field": null, + "message": "authorization required" } - } + ] } queryParameters: - username: + segment_id: type: string - required: true - uriParameters: {} - get: - displayName: List all Links - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "domain": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "username": { - "type": "string" - }, - "user_id": { - "type": "integer" - }, - "default": { - "type": "boolean" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "dns": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } - } - } - } - } - } - example: |- - [ - { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": true, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - }, - { - "id": 2, - "domain": "example2.com", - "subdomain": "news", - "username": "john@example.com", - "user_id": 8, - "default": false, - "valid": false, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "news.example2.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": false, - "type": "cname", - "host": "8.example2.com", - "data": "sendgrid.net" - } - } - } - ] - queryParameters: - limit: - type: string + description: The ID of the segment you are updating. post: - displayName: Create a Link - description: |- - This is a place for notes and extra information about this endpoint. It is written - in Markdown - more info in the [documentation](/docs/designer#markdown). - - There are several special markdown helpers that automatically build tables - and html off of your endpoint definition. You can find some examples in this content. - - Click the "Open Editor" button above to start editing this content. + displayName: Create a Segment + description: "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. \n\nSegments may contain multiple condtions, joined by an \"and\" or \"or\" in the \"and_or\" field. The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." body: application/json: example: |- { - "domain": "example.com", - "subdomain": "mail", - "default": true - } - schema: |- - { - "type": "object", - "properties": { - "domain": { - "type": "string" + "name": "Last Name Miller", + "list_id": 4, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" }, - "subdomain": { - "type": "string" + { + "field": "last_clicked", + "value": "01/02/2015", + "operator": "gt", + "and_or": "and" }, - "default": { - "type": "boolean" + { + "field": "clicks.campaign_identifier", + "value": "513", + "operator": "eq", + "and_or": "or" } - } + ] + } + schema: |- + { + "$ref": "#/definitions/contactdb_segments" } headers: {} responses: - '201': + '200': body: application/json: schema: |- { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "domain": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "username": { - "type": "string" - }, - "user_id": { - "type": "integer" - }, - "default": { - "type": "boolean" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "dns": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } - } - } - } + "$ref": "#/definitions/contactdb_segments_with_id" } example: |- { "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" + "name": "Last Name Miller", + "list_id": 4, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" + { + "field": "last_clicked", + "value": "01/02/2015", + "operator": "gt", + "and_or": "and" + }, + { + "field": "clicks.campaign_identifier", + "value": "513", + "operator": "eq", + "and_or": "or" } - } + ], + "recipient_count": 0 } - queryParameters: - limit: - type: number - description: Number of domains to return. Defaults to 50. - offset: - type: number - description: Paging offset. Defaults to 0. - '/{link_id}': - displayName: '{link_id}' - description: '' - /subuser: - displayName: subuser - description: '' - uriParameters: {} - post: - displayName: Associate Link + '400': body: application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } example: |- { - "username": "jane@example.com" + "errors": [ + { + "message": "request body is not valid json" + }, + { + "message": "invalid value is passed into one of the request body parameters" + }, + { + "field": "field", + "message": "field and set value is not passed into the request body" + }, + { + "field": "value", + "message": "value and set value is not passed into the request body" + }, + { + "field": "operator", + "message": "operator and set value is not passed into the request body" + }, + { + "field": "and_or", + "message": "and_or is not set on more than one condition and less than all conditions" + }, + { + "field": "and_or", + "message": "and_or is set on all conditions" + }, + { + "field": "and_or", + "message": "and_or is set on the only condition passed" + }, + { + "field": "and_or", + "message": "and_or and set value is not passed into the request body" + }, + { + "field": "list_id", + "message": "the list_id is not valid" + }, + { + "field": "name", + "message": "the name is not valid" + } + ] } + description: |- + "name" : "Returned if the name is not valid" + "list_id" : "Returned if the list_id is not valid" + "and_or" : "Returned if and_or and set value is not passed into the request body" + "and_or" : "Returned if and_or is set on the only condition passed" + "and_or" : "Returned if and_or is set on all conditions" + "and_or" : "Returned if and_or is not set on more than one condition and less than all conditions" + "operator" : "Returned if operator and set value is not passed into the request body" + "value" : "Returned if value and set value is not passed into the request body" + "field" : "Returned if field and set value is not passed into the request body" + "" : "Returned if request body is not valid json" + "" : "Returned if invalid value is passed into one of the request body parameters" + '401': + body: + application/json: schema: |- { - "type": "object", - "properties": { - "username": { - "type": "string" + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" } - } + ] } + queryParameters: {} + /recipients: + displayName: recipients + description: '' + '/{recipient_id}': + displayName: '{recipient_id}' + description: '' + /lists: + displayName: lists + description: '' + uriParameters: {} + get: + displayName: Get the Lists the Recipient Is On + description: |- + Each recipient can be on many lists. This endpoint gives you the lists this recipient is associated to. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: '200': @@ -4496,652 +2884,485 @@ documentation: { "type": "object", "properties": { - "id": { - "type": "integer" - }, - "domain": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "username": { - "type": "string" - }, - "user_id": { - "type": "integer" - }, - "default": { - "type": "boolean" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "dns": { - "type": "object", - "properties": { - "domain_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "owner_cname": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } + "lists": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_list" } } } } example: |- { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" + "lists": [ + { + "id": 1234, + "name": "Example list", + "recipient_count": 42 } - } + ] } - queryParameters: {} - /ips: - displayName: ips - description: '' - '/{id}': - displayName: '{id}' - description: '' - uriParameters: {} - get: - displayName: Retrieve an IP + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "recipient ID is invalid" + } + ] + } + description: '"recipient_id" : "Returned if recipient_id is not valid"' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "recipient id not found" + } + ] + } + description: '"recipient_id" : "Returned if record for the recipient id does not exist"' + queryParameters: + recipient_id: + type: string + description: The ID of the recipient you are requesting lists for. + required: true + uriParameters: + recipient_id: + type: string + delete: + displayName: Delete a Recipient + description: |- + Delete a single recipient from your contact database, by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '200': + '204': body: application/json: schema: |- { "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "rdns": { - "type": "string" - }, - "users": { - "type": "array", - "items": { - "type": "object", - "properties": { - "username": { - "type": "string" - }, - "user_id": { - "type": "integer" - } - } - } - }, - "subdomain": { - "type": "string" - }, - "domain": { - "type": "string" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "a_record": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } + "properties": {} + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "recipient not found" } - } + ] + } + description: '"recipient_id" : "Returned if recipient_id is not valid"' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ + "errors": [ { - "username": "john@example.com", - "user_id": 7 + "field": null, + "message": "authorization required" } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.1" - } + ] } - queryParameters: {} - delete: - displayName: Delete an IP + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "recipient_id is not valid" + } + ] + } + description: '"recipient_id" : "Returned if record for recipient id does not exist"' + queryParameters: + recipient_id: + type: string + description: The ID of the recipient to be deleted. + required: true + get: + displayName: Retrieve a single recipient + description: |- + Retrieve a single recipient by ID from your contact database. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '204': + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "$ref": "#/definitions/contactdb_recipient" } example: '' - queryParameters: {} - /validate: - displayName: validate - description: '' - uriParameters: {} - post: - displayName: Validate an IP - body: {} - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "valid": { - "type": "boolean" - }, - "validation_results": { - "type": "object", - "properties": { - "a_record": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "reason": { - "type": "null" - } - } - } - } - } - } - } - example: |- - { - "id": 1, - "valid": true, - "validation_results": { - "a_record": { - "valid": true, - "reason": null - } - } - } - '400': - body: - application/json: - schema: '{}' - example: '' - description: Unexpected error in API call. See HTTP response body for details. - queryParameters: {} + '400': + body: + application/json: + schema: '{}' + example: '' + description: '"recipient_id" : "Returned if recipient_id is not valid"' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: '{}' + example: '' + description: '"recipient_id" : "Returned if record for recipient id does not exist"' + queryParameters: + recipient_id: + type: string + description: The ID of the created recipient. + /search: + displayName: search + description: '' + uriParameters: {} + get: + displayName: Get Recipients Matching Search Criteria + description: |- + Search the recipients in your contactdb. + + field_name: + + * is a variable that is substituted for your actual custom field name from your recipient. + * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) + * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert + your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to + Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through + Mon, 02 Feb 2015 23:59:59 GMT. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "recipients": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_recipient" + } + } + } + } + example: |- + { + "recipients": [ + { + "created_at": 1422313607, + "email": "jones@example.com", + "first_name": null, + "id": "YUBh", + "last_clicked": null, + "last_emailed": null, + "last_name": "Jones", + "last_opened": null, + "updated_at": 1422313790, + "custom_fields": [ + { + "id": 23, + "name": "pet", + "value": "Fluffy", + "type": "text" + } + ] + } + ] + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "The following parameters are not custom fields or reserved fields: [{field_name}]" + }, + { + "message": "No search params are specified" + } + ] + } + description: |- + "" : "Returned if no search params are specified" + "field" : "Returned if the provided field is invalid or does not exist" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: + '{field_name}': + type: string uriParameters: {} - post: - displayName: Create an IP - body: - application/json: - example: |- - { - "ip": "192.168.1.1", - "subdomain": "email", - "domain": "example.com" - } - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "subdomain": { - "type": "string" - }, - "domain": { - "type": "string" - } - } - } + delete: + displayName: Delete Recipient + description: |- + Deletes one or more recipients. The body is a list of recipient ids to delete. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '201': + '200': + body: + application/json: + schema: '{}' + example: '' + '400': body: application/json: schema: |- { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "ip": { - "type": "string" - }, - "rnds": { - "type": "string" - }, - "users": { - "type": "array", - "items": {} - }, - "subdomain": { - "type": "string" - }, - "domain": { - "type": "string" - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - }, - "a_record": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - } - } + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 123, - "ip": "192.168.1.2", - "rnds": "o1.email.example.com", - "users": [], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.2" - } + "errors": [ + { + "message": "No recipient ids provided" + } + ] } - queryParameters: {} - get: - displayName: List all IPs - headers: {} - responses: - '200': + description: |- + "" : "Returned if no recipients are deleted" + "" : "Returned if all of the provided recipient ids are invalid" + "" : "Returned if request body is not valid json" + '401': body: application/json: schema: |- { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "ip": { - "type": "string" - }, - "rdns": { - "type": "string" - }, - "users": { - "type": "array", - "items": { - "properties": { - "user_id": { - "type": "number" - }, - "username": { - "type": "string" - } - } - } - }, - "subdomain": { - "type": "string" - }, - "domain": { - "type": "string" - }, - "a_record": { - "type": "object", - "properties": { - "valid": { - "type": "boolean" - }, - "type": { - "type": "string" - }, - "host": { - "type": "string" - }, - "data": { - "type": "string" - } - } - }, - "valid": { - "type": "boolean" - }, - "legacy": { - "type": "boolean" - } - } - } + "$ref": "#/definitions/global:ErrorResponse" } example: |- - [ - { - "id": 1, - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example.com", - "user_id": 8 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.1" - } - }, - { - "id": 2, - "ip": "192.168.1.2", - "rnds": "o2.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example2.com", - "user_id": 9 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o2.email.example.com", - "data": "192.168.1.2" + { + "errors": [ + { + "field": null, + "message": "authorization required" } - } - ] - queryParameters: - limit: - type: string -/asm: - displayName: asm - description: '' - /groups: - displayName: groups - description: '' - '/{group_id}': - displayName: '{group_id}' + ] + } + queryParameters: {} + /count: + displayName: count description: '' uriParameters: {} - delete: - displayName: Delete a suppression group. + get: + displayName: Get a Count of Recipients description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. + Get a count of the current number of recipients in your contact database. - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: - '204': + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "$ref": "#/definitions/contactdb_recipient_count" + } + example: |- + { + "recipient_count": 1234 + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } - example: '' queryParameters: {} - /suppressions: - displayName: suppressions - description: '' - '/{email}': - displayName: '{email}' - description: '' - uriParameters: {} - delete: - displayName: Delete a Suppression from a Group - description: 'Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.' - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - queryParameters: {} - uriParameters: {} - get: - displayName: Get suppressed addresses for a given group. - description: 'Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.' - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "string" + patch: + displayName: Update Recipient + description: |- + Updates one or more recipients. The body is an array of recipient objects. + + It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + body: + application/json: + example: |- + [ + { + "email": "jones@example.com", + "last_name": "Jones", + "first_name": "Guy" + } + ] + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email" + }, + "last_name": { + "type": "string", + "description": "The last name of the recipient. This is one of the default custom fields." + }, + "first_name": { + "type": "string", + "description": "The first name of the recipient. This is one of the default custom fields." } - } - example: |- - [ - "example@example.com", - "example2@example.com" + }, + "required": [ + "email" ] - queryParameters: {} - post: - displayName: Add Suppressions to a Group - description: 'Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.' + } + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/contactdb_recipient_response" + } + example: '' + '400': body: application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } example: |- { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" + "errors": [ + { + "field": null, + "message": "Request body is not valid json" + } ] } + description: '"" : "Returned if request body is not valid json"' + '401': + body: + application/json: schema: |- { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" - } + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" } - } + ] } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - example: |- - { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" - ] - } - queryParameters: {} - get: - displayName: Get information on a single suppression group. - description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. - - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "last_email_sent_at": { - "type": "null" - }, - "is_default": { - "type": "boolean" - }, - "unsubscribes": { - "type": "number" - } - } - } - example: |- - { - "id": 100, - "name": "Newsletters", - "description": "Our monthly newsletter.", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 400 - } - queryParameters: {} - uriParameters: {} + queryParameters: {} get: - displayName: Retrieve all suppression groups associated with the user. + displayName: "List Recipients [waiting on Bryan Adamson's response]" description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. + Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of + the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: '200': @@ -5149,222 +3370,176 @@ documentation: application/json: schema: |- { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "name": { - "type": [ - "string", - "null" - ] - }, - "description": { - "type": [ - "string", - "null" - ] - }, - "last_email_sent_at": { - "type": [ - "object", - "null" - ], - "properties": {} - }, - "is_default": { - "type": "boolean" - }, - "unsubscribes": { - "type": "number" + "title": "List Recipients response", + "type": "object", + "properties": { + "recipients": { + "type": "array", + "items": { + "type": "object" } } - } + }, + "required": [ + "recipients" + ] + } + example: '' + '400': + body: + application/json: + schema: '{}' + example: '' + description: |- + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- - [ - { - "id": 1234, - "name": "Unsubscribe Group", - "description": "An Unsubscribe Group", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 1234 - }, - { - "id": 1234, - "name": "Unsubscribe Group", - "description": "An Unsubscribe Group", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 1234 - } - ] - queryParameters: {} + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: + page: + type: integer + description: Page index of first recipients to return (must be a positive integer) + page_size: + type: integer + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) post: - displayName: Create a Group + displayName: Add recipients description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. + Add a recipient to your contactdb. It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). body: application/json: example: |- - { - "name": "A group name", - "description": "A group description", - "is_default": false - } + [ + { + "email": "example@example.com", + "first_name": "", + "last_name": "User", + "age": 25 + }, + { + "email": "example2@example.com", + "first_name": "Example", + "last_name": "User", + "age": 25 + } + ] schema: |- { - "title": "Create a Group request", - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "description": { - "type": "string" + "type": "array", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address of the recipient.", + "format": "email" + }, + "first_name": { + "type": "string", + "description": "The first name of the recipient." + }, + "last_name": { + "type": "string", + "description": "The last name of the recipient." + } }, - "is_default": { - "type": "boolean" - } - }, - "required": [ - "name", - "description", - "is_default" - ] + "required": [ + "email" + ] + } } headers: {} responses: - '200': + '201': body: application/json: schema: |- { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "last_email_sent_at": { - "type": "null" - }, - "is_default": { - "type": "boolean" + "$ref": "#/definitions/contactdb_recipient_response" + } + example: |- + { + "error_count": 1, + "error_indices": [ + 2 + ], + "new_count": 2, + "persisted_recipients": [ + "YUBh", + "bWlsbGVyQG1pbGxlci50ZXN0" + ], + "updated_count": 0, + "errors": [ + { + "message": "Invalid email.", + "error_indices": [ + 2 + ] } - } + ] + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "id": 1234, - "name": "A group name", - "description": "A group description", - "last_email_sent_at": null, - "is_default": false + "errors": [ + { + "field": null, + "message": "Request body is not valid json" + } + ] } - queryParameters: {} - '/{unsubscribe_group_id}': - displayName: '{unsubscribe_group_id}' - description: '' - uriParameters: {} - patch: - displayName: Update unsubscribe groups - body: - application/json: - example: |- - { - "id": 1234, - "name": "A group name", - "description": "A group description", - "is_default": true - } - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "is_default": { - "type": "boolean" - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "last_email_sent_at": { - "type": [ - "string", - "null" - ], - "_isOpen": true - }, - "is_default": { - "type": "boolean" - } - } - } - example: |- - { - "id": 1234, - "name": "A group name", - "description": "A group description.", - "last_email_sent_at": null, - "is_default": true - } - queryParameters: {} - /suppressions: - displayName: suppressions - description: '' - '/{email}': - displayName: '{email}' + description: '"" : "Returned if request body is not valid json"' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + /billable_count: + displayName: billable_count description: '' uriParameters: {} - delete: - displayName: Delete a Global Suppression - headers: {} - responses: - '200': - body: - application/json: - schema: '{}' - example: '' - queryParameters: {} get: - displayName: Retrieve a Global Suppression + displayName: Get the count of billable recipients + description: |- + You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: '200': @@ -5372,107 +3547,36 @@ documentation: application/json: schema: |- { - "title": "Retrieve a Global Suppression response", - "type": "object", - "properties": { - "recipient_email": { - "type": "string" - } - }, - "required": [ - "recipient_email" - ] + "$ref": "#/definitions/contactdb_recipient_count" } - example: '' - queryParameters: {} - /global: - displayName: global - description: '' - uriParameters: {} - post: - displayName: Add recipient addresses to the global suppression group. - description: Global Suppressions are email addresses that will not receive any emails. - body: - application/json: - example: |- - { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" - ] - } - schema: |- - { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" - } - } + example: |- + { + "recipient_count": 1234 } - } - headers: {} - responses: - '200': + '401': body: application/json: schema: |- { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" - } - } - } + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" + "errors": [ + { + "field": null, + "message": "authorization required" + } ] } queryParameters: {} - '/{email_address}': - displayName: '{email_address}' - description: '' - uriParameters: {} - get: - displayName: Check if a recipient address is in the global suppressions group. - description: Global Suppressions are email addresses that will not receive any emails. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "recipient_email": { - "type": "string" - } - } - } - example: |- - { - "recipient_email": "test1@example.com" - } - queryParameters: {} -/tracking_settings: - displayName: tracking_settings - description: '' - /open: - displayName: open + /custom_fields: + displayName: custom_fields description: '' uriParameters: {} get: - displayName: Get Open Tracking Settings + displayName: List All Custom Fields + description: "Get all custom fields. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." headers: {} responses: '200': @@ -5480,100 +3584,284 @@ documentation: application/json: schema: |- { + "title": "List All Custom Fields response", "type": "object", "properties": { - "enabled": { - "type": "boolean" + "custom_fields": { + "type": "array", + "items": { + "$ref": "#/definitions/contactdb_custom_field_with_id" + } } - } + }, + "required": [ + "custom_fields" + ] } example: |- { - "enabled": true - } - queryParameters: {} - patch: - displayName: Update Open Tracking Settings - body: - application/json: - example: |- - { - "enabled": true - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } + "lists": [ + { + "id": 1, + "name": "the jones", + "recipient_count": 1 + } + ] } - } - headers: {} - responses: - '200': + '401': body: application/json: schema: |- { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "enabled": true + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } queryParameters: {} - /click: - displayName: click - description: '' - uriParameters: {} - patch: - displayName: Update Click Tracking Settings - body: - application/json: - example: |- - { - "enabled": true - } - schema: |- - { + '/{custom_field_id}': + displayName: '{custom_field_id}' + description: '' + uriParameters: + custom_field_id: + type: string + delete: + displayName: Delete a Custom Field + description: |- + Delete a custom field by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + headers: {} + responses: + '202': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "message": "Custom Field delete is processing." + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "Custom field in use by one or more segment conditions" + }, + { + "message": "Custom field ID does not exist" + } + ] + } + description: '"id" : "Returned if custom_field_id is not valid"' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "Custom field ID does not exist" + } + ] + } + description: '"custom_field_id" : "Returned if custom_field_id does not exist"' + queryParameters: {} + get: + displayName: Get a Custom Field + description: |- + Get a custom field by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/contactdb_custom_field_with_id" + } + example: |- + { + "id": 1, + "name": "pet", + "type": "text" + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "invalid id" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "Custom field ID does not exist" + } + ] + } + description: '"custom_field_id" : "Returned if custom_field_id does not exist"' + queryParameters: + custom_field_id: + type: number + description: The ID of the custom field you would like to retrieve + required: true + post: + displayName: Create a Custom Field + description: |- + Create a custom field. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + body: + application/json: + example: |- + { + "name": "pet", + "type": "text" + } + schema: |- + { "type": "object", "properties": { - "enabled": { - "type": "boolean" + "name": { + "type": "string" + }, + "type": { + "type": "string" } } } headers: {} responses: - '200': + '201': body: application/json: schema: |- { "type": "object", "properties": { - "enable_text": { - "type": "boolean" + "id": { + "type": "integer" }, - "enabled": { - "type": "boolean" + "name": { + "type": "string" + }, + "type": { + "type": "string" } } } example: |- { - "enable_text": false, - "enabled": true + "id": 1, + "name": "pet", + "type": "text" + } + '400': + body: + application/json: + schema: '{}' + example: |- + { + "errors": [ + { + "field": null, + "message": "Returned if request body is invalid JSON" + }, + { + "field": "type", + "message": "Returned if custom field type is invalid or not provided" + }, + { + "field": "name", + "message": "Returned if custom field name is not provided" + } + ] } + description: |- + "" : "Returned if request body is invalid JSON" + "type" : "Returned if custom field type is invalid or not provided" + "name" : "Returned if custom field name is not provided" queryParameters: {} + /reserved_fields: + displayName: reserved_fields + description: '' + uriParameters: {} get: - displayName: Get Click Track Settings + displayName: Get reserved custom fields fields. + description: |- + List fields that are reserved and can't be used for custom field names. [GET] + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). headers: {} responses: '200': @@ -5581,2473 +3869,2627 @@ documentation: application/json: schema: |- { + "title": "List fields that are reserved and can't be used for custom field names. response", "type": "object", "properties": { - "enable_text": { - "type": "boolean" - }, - "enabled": { - "type": "boolean" + "reserved_fields": { + "type": "array", + "description": "The reserved fields that are already set up within custom fields.", + "items": { + "$ref": "#/definitions/contactdb_custom_field" + } } - } + }, + "required": [ + "reserved_fields" + ] } example: |- { - "enable_text": false, - "enabled": true - } - queryParameters: {} - /subscription: - displayName: subscription - description: '' - uriParameters: {} - patch: - displayName: Update Subscription Tracking Settings - body: - application/json: - example: |- - { - "enabled": true, - "landing": "landing page html", - "url": "url", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "landing": { - "type": "string" - }, - "url": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - queryParameters: {} - get: - displayName: Get Subscription Tracking Settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" + "reserved_fields": [ + { + "name": "first_name", + "type": "text" }, - "plain_content": { - "type": "string" + { + "name": "last_name", + "type": "text" }, - "replace": { - "type": "string" + { + "name": "email", + "type": "text" }, - "url": { - "type": "string" - } - } - } - example: "{\n \"enabled\": true,\n \"html_content\": \"

Something something unsubscribe <% %> something something

\\n\",\n \"landing\": \"

subscribehere

\\n\",\n \"plain_content\": \"Something something unsubscribe <% %> something something\",\n \"replace\": \"thetag\",\n \"url\": \"\"\n}" - queryParameters: {} - uriParameters: {} - get: - displayName: Get Tracking Settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - queryParameters: - limit: - type: string - offset: - type: string - /google_analytics: - displayName: google_analytics - description: '' - uriParameters: {} - get: - displayName: Get Google Analytics Settings - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" + { + "name": "created_at", + "type": "date" }, - "utm_campaign": { - "type": "string" + { + "name": "updated_at", + "type": "date" }, - "utm_content": { - "type": "string" + { + "name": "last_emailed", + "type": "date" }, - "utm_medium": { - "type": "string" + { + "name": "last_clicked", + "type": "date" }, - "utm_source": { - "type": "string" + { + "name": "last_opened", + "type": "date" }, - "utm_term": { - "type": "string" + { + "name": "my_custom_field", + "type": "text" } - } - } - example: |- - { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" - } - queryParameters: {} - patch: - displayName: Update Google Analytics Settings - body: - application/json: - example: |- - { - "enabled": false - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } + ] } - } - headers: {} - responses: - '200': + '401': body: application/json: schema: |- { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } - } + "$ref": "#/definitions/global:ErrorResponse" } example: |- { - "enabled": false, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] } queryParameters: {} -/devices: - displayName: devices +/templates: + displayName: templates description: '' - /stats: - displayName: stats + '/{template_id}': + displayName: '{template_id}' description: '' - uriParameters: {} - get: - displayName: Gets email statistics by device type. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "properties": { - "type": { - "type": "string" - }, - "name": { - "type": "string" - }, - "metrics": { - "type": "object", - "properties": { - "opens": { - "type": "number" - }, - "unique_opens": { - "type": "number" - } - } - } - } - } - } - } - } - } - example: |- - [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, + /versions: + displayName: versions + description: '' + uriParameters: {} + post: + displayName: Create a new transactional template version. + description: | + **This endpoint allows you to create a new version of a template.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + body: + application/json: + example: |- + { + "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", + "active": 1, + "name": "example_version_name", + "html_content": "<%body%>", + "plain_content": "<%body%>", + "subject": "<%subject%>" + } + schema: |- + { + "$ref": "#/definitions/transactional_template_version" + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The id of the new transactional template version." + }, + "updated_at": { + "type": "string", + "description": "The date and time that this transactional template version was updated." + }, + "Transactional Template Version": { + "$ref": "#/definitions/transactional_template_version" + } + }, + "required": [ + "id", + "updated_at" + ] + } + example: |- + { + "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", + "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", + "active": 1, + "name": "example_version_name", + "html_content": "<%body%>", + "plain_content": "<%body%>", + "subject": "<%subject%>", + "updated_at": "2014-03-19 18:56:33" + } + queryParameters: {} + '/{version_id}': + displayName: '{version_id}' + description: '' + uriParameters: + version_id: + type: string + get: + displayName: Retrieve a specific transactional template version. + description: |- + **This endpoint allows you to retrieve a specific version of a template.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + headers: {} + responses: + '200': + body: + application/json: + schema: |- { - "date": "2015-10-15", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the template version." + }, + "updated_at": { + "type": "string", + "description": "The date and time that the template version was last updated." + }, + "Transactional Template Version": { + "$ref": "#/definitions/transactional_template_version" } + }, + "required": [ + "id", + "updated_at" ] - }, + } + example: |- { - "date": "2015-10-16", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, + "id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f", + "template_id": "d51480ca-ca3f-465c-bc3e-ceb71d73c38d", + "active": 1, + "name": "version 1 name", + "html_content": "<%body%>", + "plain_content": "<%body%>", + "subject": "<%subject%>", + "updated_at": "2014-03-19 18:56:33" + } + queryParameters: {} + /activate: + displayName: activate + description: '' + uriParameters: {} + post: + displayName: Activate a transactional template version. + description: |- + **This endpoint allows you to activate a version of one of your templates.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + body: + application/json: + example: '' + schema: |- + { + "type": "object", + "properties": {} + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the template version." + }, + "updated_at": { + "type": "string", + "description": "The date and time that the version was last updated." + }, + "Transactional Template Version": { + "$ref": "#/definitions/transactional_template_version" + } + }, + "required": [ + "id", + "updated_at" + ] + } + example: |- + { + "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", + "template_id": "e3a61852-1acb-4b32-a1bc-b44b3814ab78", + "active": 1, + "name": "example_version_name", + "html_content": "<%body%>", + "plain_content": "<%body%>", + "subject": "<%subject%>", + "updated_at": "2014-06-12 11:33:00" + } + queryParameters: {} + delete: + displayName: Delete a transactional template version. + description: |- + **This endpoint allows you to delete one of your transactional template versions.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + headers: {} + responses: + '204': + body: + application/json: + schema: |- { - "date": "2015-10-17", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 1, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 2, - "unique_opens": 2 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, + "type": "null" + } + example: '' + queryParameters: {} + patch: + displayName: Edit a transactional template version. + description: |- + **This endpoint allows you to edit a version of one of your transactional templates.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + body: + application/json: + example: |- + { + "active": 1, + "name": "updated_example_name", + "html_content": "<%body%>", + "plain_content": "<%body%>", + "subject": "<%subject%>" + } + schema: |- + { + "type": "object", + "properties": { + "active": { + "type": "integer", + "description": "Indicates if the template version is active." + }, + "name": { + "type": "string", + "description": "The name of the template version." + }, + "html_content": { + "type": "string", + "description": "The HTML content of the template version." + }, + "plain_content": { + "type": "string", + "description": "The text/plain content of the template version." + }, + "subject": { + "type": "string", + "description": "The subject of the template version." + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- { - "date": "2015-10-30", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the template version." + }, + "updated_at": { + "type": "string", + "description": "The date and time that the template version was last updated." + }, + "Transactional Template Version": { + "$ref": "#/definitions/transactional_template_version" } + }, + "required": [ + "id", + "updated_at" ] - }, + } + example: |- { - "date": "2015-10-31", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] + "id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f", + "template_id": "d51480ca-ca3f-465c-bc3e-ceb71d73c38d", + "active": 1, + "name": "version 1 name", + "html_content": "<%body%>", + "plain_content": "<%body%>", + "subject": "<%subject%>", + "updated_at": "2014-03-19 18:56:33" } - ] - queryParameters: - end_date: - type: string - limit: - type: string - offset: - type: string - aggregated_by: - type: string - start_date: - type: string -/mailbox_providers: - displayName: mailbox_providers - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Gets email statistics by mailbox provider. + queryParameters: {} + uriParameters: + id: + displayName: The id of the transactional template you want to retrieve. + type: string + delete: + displayName: Delete a template. + description: | + **This endpoint allows you to delete a transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). headers: {} responses: - '200': + '204': body: application/json: schema: |- { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "properties": { - "type": { - "type": "string" - }, - "name": { - "type": "string" - }, - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "number" - }, - "bounces": { - "type": "number" - }, - "clicks": { - "type": "number" - }, - "deferred": { - "type": "number" - }, - "delivered": { - "type": "number" - }, - "drops": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "spam_reports": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - } - } - } - } - } - } - } + "type": "object", + "properties": {} + } + example: '' + queryParameters: {} + patch: + displayName: Edit a transactional template. + description: | + **This endpoint allows you to edit a transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + body: + application/json: + example: |- + { + "name": "new_example_name" + } + schema: |- + { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the transactional template.", + "maxLength": 100 } } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/transactional_template" + } example: |- - [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + { + "id": "733ba07f-ead1-41fc-933a-3976baa23716", + "name": "new_example_name", + "versions": [] + } + queryParameters: {} + get: + displayName: Retrieve a single transactional template. + description: | + **This endpoint allows you to retrieve a single transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/transactional_template" + } + example: '' + queryParameters: {} + uriParameters: {} + get: + displayName: Retrieve all transactional templates. + description: |- + **This endpoint allows you to retrieve all transactional templates.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/transactional_template" + } + } + example: '' + queryParameters: {} + post: + displayName: Create a transactional template. + description: |- + **This endpoint allows you to create a transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + body: + application/json: + example: |- + { + "name": "example_name" + } + schema: |- + { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name for the new transactional template.", + "maxLength": 100 + } + }, + "required": [ + "name" + ] + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/transactional_template" + } + example: |- + { + "id": "733ba07f-ead1-41fc-933a-3976baa23716", + "name": "example_name", + "versions": [] + } + queryParameters: {} +/whitelabel: + displayName: whitelabel + description: '' + /domains: + displayName: domains + description: '' + /default: + displayName: default + description: '' + uriParameters: {} + get: + displayName: Get the default domain whitelabel. + description: |- + **This endpoint allows you to retrieve the default whitelabel for a domain.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | domain | string |The domain to find a default domain whitelabel for. | + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/whitelabel:domain_spf" + } + example: '' + queryParameters: {} + '/{id}': + displayName: '{id}' + description: '' + /ips: + displayName: ips + description: '' + '/{ip}': + displayName: '{ip}' + description: '' + uriParameters: + ip: + type: string + delete: + displayName: Remove an IP from a domain whitelabel. + description: |- + **This endpoint allows you to remove a domain's IP address from that domain's whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer | ID of the domain whitelabel to delete the IP from. | + | ip | string | IP to remove from the domain whitelabel. | + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/whitelabel:domain_spf" + } + example: |- + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "mail@example.com", + "user_id": 7, + "ips": [], + "custom_spf": true, + "default": false, + "legacy": false, + "automatic_security": false, + "valid": false, + "dns": { + "mail_server": { + "host": "mail.example.com", + "type": "mx", + "data": "sendgrid.net", + "valid": false + }, + "subdomain_spf": { + "host": "mail.example.com", + "type": "txt", + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "valid": false + }, + "domain_spf": { + "host": "example.com", + "type": "txt", + "data": "v=spf1 include:mail.example.com -all", + "valid": false + }, + "dkim": { + "host": "s1._domainkey.example.com", + "type": "txt", + "data": "k=rsa; t=s; p=publicKey", + "valid": false + } + } + } + queryParameters: {} + uriParameters: {} + post: + displayName: Add an IP to a domain whitelabel. + description: |- + **This endpoint allows you to add an IP address to a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer | ID of the domain to which you are adding an IP | + body: + application/json: + example: |- + { + "ip": "192.168.0.1" + } + schema: |- + { + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." + } }, + "required": [ + "ip" + ] + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- { - "date": "2015-10-13", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, + "$ref": "#/definitions/whitelabel:domain_spf" + } + example: |- { - "date": "2015-10-14", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "ips": [], + "custom_spf": true, + "default": false, + "legacy": false, + "automatic_security": false, + "valid": false, + "dns": { + "mail_server": { + "host": "mail.example.com", + "type": "mx", + "data": "sendgrid.net", + "valid": false + }, + "subdomain_spf": { + "host": "mail.example.com", + "type": "txt", + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "valid": false + }, + "domain_spf": { + "host": "example.com", + "type": "txt", + "data": "v=spf1 include:mail.example.com -all", + "valid": false + }, + "dkim": { + "host": "s1._domainkey.example.com", + "type": "txt", + "data": "k=rsa; t=s; p=publicKey", + "valid": false } - ] - }, + } + } + queryParameters: {} + /validate: + displayName: validate + description: '' + uriParameters: + id: + type: string + post: + displayName: Validate a domain whitelabel. + description: |- + **This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer |ID of the domain whitelabel to validate. | + body: {} + headers: {} + responses: + '200': + body: + application/json: + schema: |- { - "date": "2015-10-15", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the domain whitelabel." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid whitelabel." + }, + "validation_resuts": { + "type": "object", + "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", + "properties": { + "mail_cname": { + "type": "object", + "description": "The CNAME record for the domain whitelabel.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this DNS record is valid." + }, + "reason": { + "type": "string", + "description": "The reason this record is invalid." + } + } + }, + "dkim1": { + "type": "object", + "description": "A DNS record for this domain whitelabel.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the DNS record is valid." + }, + "reason": { + "type": "null" + } + } + }, + "dkim2": { + "type": "object", + "description": "A DNS record for this whitelabel.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the DNS record is valid." + }, + "reason": { + "type": "null" + } + } + }, + "spf": { + "type": "object", + "description": "The SPF record for the whitelabel.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the SPF record is valid." + }, + "reason": { + "type": "null" + } + } + } } } - ] - }, + } + } + example: "{\n \"id\": 1,\n \"valid\": true,\n \"validation_resuts\": {\n \"mail_cname\": {\n \"valid\": false,\n \"reason\": \"Expected your MX record to be \\\"mx.sendgrid.net\\\" but found \\\"example.com\\\".\"\n },\n \"dkim1\": {\n \"valid\": true,\n \"reason\": null\n },\n \"dkim2\": {\n \"valid\": true,\n \"reason\": null\n },\n \"spf\": {\n \"valid\": true,\n \"reason\": null\n }\n }\n}" + '400': + body: + application/json: + schema: |- { - "date": "2015-10-16", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, + "type": "object", + "properties": {} + } + example: '' + description: Unexpected error in API call. See HTTP response body for details. + '500': + body: + application/json: + schema: |- { - "date": "2015-10-17", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "A message explaining the reason for the error." + } + }, + "required": [ + "message" + ] } } - ] - }, + } + } + example: |- { - "date": "2015-10-18", - "stats": [ + "errors": [ { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 1, - "drops": 0, - "opens": 1, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } + "message": "internal error getting TXT" } ] + } + queryParameters: {} + '/{domain_id}': + displayName: '{domain_id}' + description: '' + /subuser: + displayName: subuser + description: '' + uriParameters: {} + post: + displayName: Associate a domain whitelabel with a given user. + description: |- + **This endpoint allows you to associate a specific domain whitelabel with a subuser.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | domain_id | integer | ID of the domain whitelabel to associate with the subuser. | + body: + application/json: + example: |- + { + "username": "jane@example.com" + } + schema: |- + { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "Username to associate with the domain whitelabel." + } }, + "required": [ + "username" + ] + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- { - "date": "2015-10-25", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, + "$ref": "#/definitions/whitelabel:domain_spf" + } + example: |- { - "date": "2015-10-26", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 2, - "drops": 0, - "opens": 2, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 2 - } + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "mail@example.com", + "user_id": 7, + "ips": [], + "custom_spf": true, + "default": false, + "legacy": false, + "automatic_security": false, + "valid": false, + "dns": { + "mail_server": { + "host": "mail.example.com", + "type": "mx", + "data": "sendgrid.net", + "valid": false + }, + "subdomain_spf": { + "host": "mail.example.com", + "type": "txt", + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "valid": false + }, + "domain_spf": { + "host": "example.com", + "type": "txt", + "data": "v=spf1 include:mail.example.com -all", + "valid": false + }, + "dkim": { + "host": "s1._domainkey.example.com", + "type": "txt", + "data": "k=rsa; t=s; p=publicKey", + "valid": false } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + } + } + queryParameters: {} + uriParameters: + id: + displayName: The id of the domain whitelabel that you want to delete. + type: number + patch: + displayName: Update a domain whitelabel. + description: |- + **This endpoint allows you to update the settings for a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + body: + application/json: + example: |- + { + "default": false, + "custom_spf": true + } + schema: |- + { + "type": "object", + "properties": { + "default": { + "type": "boolean", + "default": "false", + "description": "Indicates whether this domain whitelabel should be considered the default." + }, + "custom_spf": { + "type": "boolean", + "default": "false", + "description": "Indicates whether to generate a custom SPF record for manual security." + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "title": "Update a Domain response", + "type": "object", + "properties": { + "default false": { + "description": "Inidcates whether this domain whitelabel should be considered the default. Defaults to false.", + "type": "boolean" + }, + "custom_spf false": { + "description": "Indicates whether to generate a custom SPF record for manual security. Defaults to false.", + "type": "boolean" + } + } + } + example: '' + queryParameters: {} + get: + displayName: Retrieve a domain whitelabel. + description: | + **This endpoint allows you to retrieve a specific domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/whitelabel::domain" + } + example: '' + queryParameters: {} + delete: + displayName: Delete a domain whitelabel. + description: |- + **This endpoint allows you to delete a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + headers: {} + responses: + '204': + body: + application/json: + schema: '{}' + example: '' + queryParameters: {} + /subuser: + displayName: subuser + description: '' + uriParameters: {} + get: + displayName: List the domain whitelabel associated with the given user. + description: |- + **This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | username | string | Username of the subuser to find associated whitelabels for. | + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/whitelabel:domain_spf" + } + example: |- + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "mail@example.com", + "user_id": 7, + "ips": [], + "custom_spf": true, + "default": false, + "legacy": false, + "automatic_security": false, + "valid": false, + "dns": { + "mail_server": { + "host": "mail.example.com", + "type": "mx", + "data": "sendgrid.net", + "valid": false + }, + "subdomain_spf": { + "host": "mail.example.com", + "type": "txt", + "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", + "valid": false + }, + "domain_spf": { + "host": "example.com", + "type": "txt", + "data": "v=spf1 include:mail.example.com -all", + "valid": false + }, + "dkim": { + "host": "s1._domainkey.example.com", + "type": "txt", + "data": "k=rsa; t=s; p=publicKey", + "valid": false + } + } + } + queryParameters: {} + delete: + displayName: Disassociate a domain whitelabel from a given user. + description: |- + **This endpoint allows you to disassociate a specific whitelabel from a subuser.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + | username | string | required | Username for the subuser to find associated whitelabels for. | + headers: {} + responses: + '204': + body: + application/json: + schema: '{}' + example: '' + queryParameters: {} + uriParameters: {} + post: + displayName: Create a domain whitelabel. + description: |- + **This endpoint allows you to create a whitelabel for one of your domains.** + + If you are creating a domain whitelabel that you would like a subuser to use, you have two options: + 1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. + 2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + body: + application/json: + example: |- + { + "domain": "example.com", + "subdomain": "news", + "username": "john@example.com", + "ips": [ + "192.168.1.1", + "192.168.1.2" + ], + "custom_spf": true, + "default": true, + "automatic_security": false + } + schema: |- + { + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": "Domain being whitelabeled." }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "subdomain": { + "type": "string", + "description": "The subdomain to use for this domain whitelabel." }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "username": { + "type": "string", + "description": "The username that this whitelabel will be associated with." }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "ips": { + "type": "array", + "description": "The IP addresses that will be included in the custom SPF record for this whitelabel.", + "items": { + "type": "string" + } }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "custom_spf": { + "type": "boolean", + "description": "Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security." }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "default": { + "type": "boolean", + "description": "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain." }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 + "automatic_security": { + "type": "boolean", + "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation." + } + }, + "required": [ + "domain", + "subdomain" + ] + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/whitelabel::domain" + } + example: |- + { + "id": 302183, + "user_id": 1446226, + "subdomain": "example", + "domain": "example.com", + "username": "mbernier", + "ips": [], + "custom_spf": false, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": false, + "dns": { + "mail_cname": { + "valid": false, + "type": "cname", + "host": "example.example.com", + "data": "u1446226.wl.sendgrid.net" + }, + "dkim1": { + "valid": false, + "type": "cname", + "host": "s1._domainkey.example.com", + "data": "s1.domainkey.u1446226.wl.sendgrid.net" + }, + "dkim2": { + "valid": false, + "type": "cname", + "host": "s2._domainkey.example.com", + "data": "s2.domainkey.u1446226.wl.sendgrid.net" + } + } + } + queryParameters: {} + get: + displayName: List all domain whitelabels. + description: | + **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The ID of the domain whitelabel." + }, + "user_id": { + "type": "number", + "description": "The ID of the user that this whitelabel will be associated with." + }, + "subdomain": { + "type": "string", + "description": "The subdomain created for this domain whitelabel." + }, + "domain": { + "type": "string", + "description": "The domain that this whitelabel was created for." + }, + "username": { + "type": "string", + "description": "The username that this whitelabel is associated with." + }, + "ips": { + "type": "array", + "description": "The IPs that will be included in the custom SPF record.", + "items": { + "type": "string" } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 + }, + "custom_spf": { + "type": "boolean", + "description": "Indicates if this whitelabel has custom SPF." + }, + "default": { + "type": "boolean", + "description": "Indicates if this whitelabel has been set as the default whitelabel." + }, + "legacy": { + "type": "boolean", + "description": "Indicates if this is whitelabel was created with the legacy whitelabel tool." + }, + "automatic_security": { + "type": "boolean", + "description": "Indicates if this whitelabel uses automated security." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid whitelabel or not." + }, + "dns": { + "type": "object", + "description": "The DNS records for this whitelabel that are used for authenticating the sending domain.", + "properties": { + "mail_server": { + "type": "object", + "description": "Designates which mail server is responsible for accepting messages from a domain.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid DNS record with no conflicts." + }, + "type": { + "type": "string", + "description": "The type of DNS record." + }, + "host": { + "type": "string", + "description": "The domain sending the messages." + }, + "data": { + "type": "string", + "description": "The mail server responsible for accepting messages." + } + } + }, + "subdomain_spf": { + "type": "object", + "description": "The SPF record for the subdomain used to create this whitelabel.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the SPF record is valid." + }, + "type": { + "type": "string", + "description": "The type of data in the SPF record." + }, + "host": { + "type": "string", + "description": "The domain that this SPF record will be used to authenticate." + }, + "data": { + "type": "string", + "description": "The SPF record." + } + } + }, + "dkim": { + "type": "object", + "description": "The DNS record used when creating the DKIM signature.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this DNS record is valid." + }, + "type": { + "type": "string", + "description": "The type of DNS record.", + "enum": [ + "cname", + "mx", + "txt" + ] + }, + "host": { + "type": "string", + "description": "The domain that these DNS records will be applied to.", + "format": "hostname" + }, + "data": { + "type": "string", + "description": "The DNS record." + } + } + } } } + }, + "required": [ + "id", + "user_id", + "subdomain", + "domain", + "username", + "ips", + "custom_spf", + "default", + "legacy", + "automatic_security", + "valid", + "dns" ] - }, + } + } + example: |- + [ { - "date": "2015-11-06", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "ips": [ + "192.168.1.1", + "192.168.1.2" + ], + "custom_spf": true, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": true, + "dns": { + "mail_cname": { + "host": "mail.example.com", + "type": "cname", + "data": "u7.wl.sendgrid.net", + "valid": true + }, + "spf": { + "host": "example.com", + "type": "txt", + "data": "v=spf1 include:u7.wl.sendgrid.net -all", + "valid": true + }, + "dkim1": { + "host": "s1._domainkey.example.com", + "type": "cname", + "data": "s1._domainkey.u7.wl.sendgrid.net", + "valid": true + }, + "dkim2": { + "host": "s2._domainkey.example.com", + "type": "cname", + "data": "s2._domainkey.u7.wl.sendgrid.net", + "valid": true } - ] + } }, { - "date": "2015-11-07", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } + "id": 2, + "domain": "example2.com", + "subdomain": "news", + "username": "jane@example2.com", + "user_id": 8, + "ips": [], + "custom_spf": false, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": false, + "dns": { + "mail_server": { + "host": "news.example2.com", + "type": "mx", + "data": "sendgrid.net", + "valid": false + }, + "subdomain_spf": { + "host": "news.example2.com", + "type": "txt", + "data": "v=spf1 include:sendgrid.net ~all", + "valid": false + }, + "domain_spf": { + "host": "example2.com", + "type": "txt", + "data": "v=spf1 include:news.example2.com -all", + "valid": false + }, + "dkim": { + "host": "example2.com", + "type": "txt", + "data": "k=rsa; t=s; p=publicKey", + "valid": false } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + } } ] queryParameters: limit: - type: string + type: integer + description: Number of domains to return. offset: + type: integer + description: Paging offset. + exclude_subusers: + type: boolean + description: Exclude subuser domains from the result. + username: type: string - aggregated_by: - type: string - start_date: - type: string - end_date: + description: The username associated with a whitelabel. + domain: type: string -/ips: - displayName: ips - description: '' - '/{ip_address}': - displayName: '{ip_address}' - description: '' - uriParameters: {} - get: - displayName: See which pools an IP address belongs to. - headers: {} - responses: {} - queryParameters: {} - /pools: - displayName: pools + description: Search for domain whitelabels that match the given domain. + /links: + displayName: links description: '' - '/{pool_name}': - displayName: '{pool_name}' + '/{id}': + displayName: '{id}' description: '' - /ips: - displayName: ips - description: '' - uriParameters: {} - post: - displayName: Assign an IP to a pool - body: - application/json: - example: |- - { - "ip": "0.0.0.0" - } - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string" - } - } - } - headers: {} - responses: {} - queryParameters: {} - '/{ip}': - displayName: '{ip}' - description: '' - uriParameters: {} - delete: - displayName: Remove an IP address from a pool. - headers: {} - responses: {} - queryParameters: {} - uriParameters: {} - delete: - displayName: Delete an IP pool. + uriParameters: + id: + displayName: The id of the link whitelabel that you want to delete. + type: integer + get: + displayName: Retrieve a Link Whitelabel + description: |- + **This endpoint allows you to retrieve a specific link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). headers: {} responses: - '204': + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "$ref": "#/definitions/link_whitelabel" + } + example: |- + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "default": false, + "valid": true, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "sendgrid.net" + }, + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" + } + } } - example: '' queryParameters: {} - put: - displayName: Update an IP pool’s name. + patch: + displayName: Update a Link Whitelabel + description: |- + **This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). body: application/json: example: |- { - "name": "new_pool_name" + "default": true } schema: |- { "type": "object", - "properties": {} + "properties": { + "default": { + "type": "boolean", + "description": "Indicates if the link whitelabel is set as the default, or fallback, whitelabel.", + "enum": [ + true, + false + ] + } + } } headers: {} - responses: {} - queryParameters: {} - get: - displayName: List the IPs in a specified pool. - headers: {} responses: '200': body: application/json: schema: |- { - "type": "object", - "properties": { - "pool_name": { - "type": "string" + "$ref": "#/definitions/link_whitelabel" + } + example: |- + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "default": true, + "valid": true, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "sendgrid.net" }, - "ips": { - "type": "array", - "items": { - "type": "string" - } + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" } } } + queryParameters: {} + delete: + displayName: Delete a Link Whitelabel + description: |- + **This endpoint allows you to delete a link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + headers: {} + responses: + '204': + body: + application/json: + schema: '{}' example: '' queryParameters: {} - uriParameters: {} - post: - displayName: Create an IP pool. - body: - application/json: - example: |- - { - "name": "marketing" - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string" - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string" - } - } - } - example: |- - { - "name": "marketing" - } - queryParameters: {} - get: - displayName: List all IP pools. - headers: {} - responses: {} - queryParameters: {} - /warmup: - displayName: warmup - description: '' - uriParameters: {} - post: - displayName: Add an IP to warmup. - body: - application/json: - example: |- - { - "ip": "0.0.0.0" - } - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string" + /validate: + displayName: validate + description: '' + uriParameters: + id: + displayName: The id of the link whitelabel that you want to validate. + type: integer + post: + displayName: Validate a Link Whitelabel + description: |- + **This endpoint allows you to validate a link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + body: {} + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The id of the link whitelabel." + }, + "valid": { + "type": "boolean", + "description": "Indicates if the link whitelabel is valid.", + "enum": [ + true, + false + ] + }, + "validation_results": { + "type": "object", + "description": "The individual validations results for each of the DNS records associated with this link whitelabel.", + "required": [ + "domain_cname" + ], + "properties": { + "domain_cname": { + "type": "object", + "description": "The DNS record generated for the sending domain used for this link whitelabel.", + "required": [ + "valid", + "reason" + ], + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this DNS record is valid.", + "enum": [ + true, + false + ] + }, + "reason": { + "type": [ + "string", + "null" + ], + "description": "Null if the DNS record is valid. If the DNS record is invalid, this will explain why." + } + } + }, + "owner_cname": { + "type": "object", + "description": "The DNS record created to verify the link whitelabel.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the DNS record is valid.", + "enum": [ + true, + false + ] + }, + "reason": { + "type": [ + "null", + "string" + ], + "description": "Null if valid. If the DNS record is invalid, this will explain why." + } + }, + "required": [ + "valid", + "reason" + ] + } + } + } + }, + "required": [ + "id", + "valid", + "validation_results" + ] } - } - } - headers: {} - responses: - '200': + example: "{\n \"id\": 1,\n \"valid\": true,\n \"validation_results\": {\n \"domain_cname\": {\n \"valid\": false,\n \"reason\": \"Expected CNAME to match \\\"sendgrid.net.\\\" but found \\\"example.com.\\\".\"\n },\n \"owner_cname\": {\n \"valid\": true,\n \"reason\": null\n }\n }\n}" + '400': + body: + application/json: + schema: '{}' + example: '' + description: Unexpected error in API call. See HTTP response body for details. + '500': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "errors": { + "type": "array", + "description": "The reasons why the validation failed.", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "The reason why the link whitelabel could not be validated." + } + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + } + example: |- + { + "errors": [ + { + "message": "internal error getting CNAME" + } + ] + } + queryParameters: {} + '/{link_id}': + displayName: '{link_id}' + description: '' + /subuser: + displayName: subuser + description: '' + uriParameters: {} + post: + displayName: Associate a Link Whitelabel + description: |- + **This endpoint allows you to associate a link whitelabel with a subuser account.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). body: application/json: + example: |- + { + "username": "jane@example.com" + } schema: |- { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "start_date": { - "type": "integer" - } + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The username of the subuser account that you want to associate the link whitelabel with." } } } - example: |- - [ + headers: {} + responses: + '200': + body: + application/json: + schema: |- { - "ip": "0.0.0.0", - "start_date": 1409616000 + "$ref": "#/definitions/link_whitelabel" } - ] - queryParameters: {} - '/{ip_address}': - displayName: '{ip_address}' + example: |- + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "default": false, + "valid": true, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "sendgrid.net" + }, + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" + } + } + } + queryParameters: {} + /subuser: + displayName: subuser description: '' uriParameters: {} - delete: - displayName: Remove an IP from warmup. + get: + displayName: Retrieve Associated Link Whitelabel + description: |- + **This endpoint allows you to retrieve the associated link whitelabel for a subuser.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). headers: {} responses: - '204': + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "$ref": "#/definitions/link_whitelabel" } - example: '' - queryParameters: {} - get: - displayName: Get warmup status for a particular IP. - headers: {} - responses: {} - queryParameters: {} - get: - displayName: Get all IPs that are currently warming up. - headers: {} - responses: {} - queryParameters: {} - uriParameters: {} - get: - displayName: List all IPs - description: |- - See a list of all assigned and unassigned IPs. - Response includes warm up status, pools, assigned subusers, and whitelabel info. - The start_date field corresponds to when warmup started for that IP. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" + example: |- + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "default": false, + "valid": true, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "sendgrid.net" }, - "subusers": { - "type": "array", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "object", - "properties": {} - } - }, - "warmup": { - "type": "boolean" - }, - "start_date": { - "type": [ - "number", - "null" - ] - }, - "whitelabeled": { - "type": "boolean" + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" } } } - } - example: |- - [ + queryParameters: + username: + type: string + description: The username of the subuser to retrieve associated link whitelabels for. + required: true + delete: + displayName: Disassociate a Link Whitelabel + description: |- + **This endpoint allows you to disassociate a link whitelabel from a subuser.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + headers: {} + responses: + '204': + body: + application/json: + schema: '{}' + example: '' + queryParameters: + username: + type: string + description: The username of the subuser account that you want to disassociate a link whitelabel from. + required: true + /default: + displayName: default + description: '' + uriParameters: {} + get: + displayName: Retrieve a Default Link Whitelabel + description: |- + **This endpoint allows you to retrieve the default link whitelabel.** + + Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: + + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- { - "ip": "127.0.0.1", - "subusers": [ - "example_subuser1", - "example_subuser2" - ], - "rdns": "o1.em.example.com", - "pools": [], - "warmup": true, - "start_date": 1250337600, - "whitelabeled": true - }, + "$ref": "#/definitions/link_whitelabel" + } + example: |- { - "ip": "127.0.0.1", - "subusers": [], - "pools": [], - "warmup": false, - "start_date": null, - "whitelabeled": false + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "default": false, + "valid": true, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "sendgrid.net" + }, + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" + } + } } - ] - queryParameters: - ip: - type: string - description: The IP address to get - exclude_whitelabels: - type: string - description: Should we exclude whitelabels? - subuser: - type: string - description: The subuser you are requesting for. - limit: - type: string - default: 10 - description: The number of IPs you want returned at the same time. - offset: - type: string - default: 0 - description: The offset for the number of IPs that you are requesting. - /assigned: - displayName: assigned - description: '' + queryParameters: + domain: + type: string + description: The domain to match against when finding a corresponding link whitelabel. uriParameters: {} - get: - displayName: List all assigned IPs - description: Retrieve a list of your IP addresses. + post: + displayName: Create a Link Whitelabel + description: |- + **This endpoint allows you to create a new link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + body: + application/json: + example: |- + { + "domain": "example.com", + "subdomain": "mail", + "default": true + } + schema: |- + { + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": "The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address." + }, + "subdomain": { + "type": "string", + "description": "The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel." + }, + "default": { + "type": "boolean", + "description": "Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.", + "enum": [ + true, + false + ] + } + }, + "required": [ + "domain", + "subdomain" + ] + } headers: {} responses: - '200': + '201': body: application/json: schema: |- { - "title": "List all assigned IPs response", - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean" + "$ref": "#/definitions/link_whitelabel" + } + example: |- + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "default": false, + "valid": true, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "sendgrid.net" }, - "start_date": { - "type": "integer", - "format": "int64" + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" } - }, - "required": [ - "ip", - "pools", - "warmup", - "start_date" - ] + } } - example: '' - queryParameters: {} -/api_keys: - displayName: api_keys - description: '' - '/{api_key_id}': - displayName: '{api_key_id}' - description: '' - uriParameters: {} - delete: - displayName: Delete API keys + queryParameters: + limit: + type: integer + description: Number of domains to return. + offset: + type: integer + description: Paging offset. + get: + displayName: Retrieve all link whitelabels description: |- - **Revoke an existing API Key** - - Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + **This endpoint allows you to retrieve all link whitelabels.** - ## URI Parameters + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are deleting.| + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). headers: {} responses: - '204': + '200': body: application/json: schema: |- { - "type": "null" - } - example: '' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" + "type": "array", + "items": { + "$ref": "#/definitions/link_whitelabel" + } } example: |- - { - "errors": [ - { - "field": null, - "message": "unable to find API Key" + [ + { + "id": 1, + "domain": "example.com", + "subdomain": "mail", + "username": "john@example.com", + "user_id": 7, + "default": true, + "valid": true, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "sendgrid.net" + }, + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" + } } - ] + }, + { + "id": 2, + "domain": "example2.com", + "subdomain": "news", + "username": "john@example.com", + "user_id": 8, + "default": false, + "valid": false, + "legacy": false, + "dns": { + "domain_cname": { + "valid": true, + "type": "cname", + "host": "news.example2.com", + "data": "sendgrid.net" + }, + "owner_cname": { + "valid": false, + "type": "cname", + "host": "8.example2.com", + "data": "sendgrid.net" + } + } + } + ] + queryParameters: + limit: + type: integer + description: Limits the number of results returned per page. + /ips: + displayName: ips + description: '' + uriParameters: {} + get: + displayName: Retrieve all IP whitelabels + description: |- + **This endpoint allows you to retrieve all of the IP whitelabels that have been createdy by this account.** + + You may include a search key by using the "ip" parameter. This enables you to perform a prefix search for a given IP segment (e.g. "192."). + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/ip_whitelabel" + } } - queryParameters: {} - put: - displayName: 'Update the name & scopes of an API Key' + example: |- + [ + { + "id": 1, + "ip": "192.168.1.1", + "rdns": "o1.email.example.com", + "users": [ + { + "username": "john@example.com", + "user_id": 7 + }, + { + "username": "jane@example.com", + "user_id": 8 + } + ], + "subdomain": "email", + "domain": "example.com", + "valid": true, + "legacy": false, + "a_record": { + "valid": true, + "type": "a", + "host": "o1.email.example.com", + "data": "192.168.1.1" + } + }, + { + "id": 2, + "ip": "192.168.1.2", + "rdns": "o2.email.example.com", + "users": [ + { + "username": "john@example.com", + "user_id": 7 + }, + { + "username": "jane@example2.com", + "user_id": 9 + } + ], + "subdomain": "email", + "domain": "example.com", + "valid": true, + "legacy": false, + "a_record": { + "valid": true, + "type": "a", + "host": "o2.email.example.com", + "data": "192.168.1.2" + } + } + ] + queryParameters: + limit: + type: integer + description: The number of results to retrieve. + offset: + type: integer + description: The point in the list of results to begin retrieving IPs from. + ip: + type: string + description: The IP segment that you would like to use in a prefix search. + post: + displayName: Create an IP whitelabel description: |- - A JSON request body with a "name" property is required. - Most provide the list of all the scopes an api key should have. + **This endpoint allows you to create an IP whitelabel.** - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + When creating an IP whitelable, you should use the same subdomain that you used when you created a domain whitelabel. - ## URI Parameters + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - | Param | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are updating.| + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). body: application/json: example: |- { - "name": "A New Hope", - "scopes": [ - "user.profile.read", - "user.profile.update" - ] + "ip": "192.168.1.1", + "subdomain": "email", + "domain": "example.com" } schema: |- { "type": "object", "properties": { - "name": { - "type": "string" + "ip": { + "type": "string", + "description": "The IP address that you want to whitelabel." }, - "scopes": { - "type": "array", - "items": { - "type": "string" - } + "subdomain": { + "type": "string", + "description": "The subdomain that will be used to send emails from the IP. Should be the same as the subdomain used for your domain whitelabel." + }, + "domain": { + "type": "string", + "description": "The root, or sending, domain that will be used to send message from the IP." } - } + }, + "required": [ + "ip", + "subdomain", + "domain" + ] } headers: {} responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/api_key_name_id_scopes" - } - example: |- - { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope", - "scopes": [ - "user.profile.read", - "user.profile.update" - ] - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "expected JSON request body with 'name' property" - } - ] - } - description: Unexpected error in API call. See HTTP response body for details. - '401': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - '404': + '201': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/ip_whitelabel" } example: |- { - "errors": [ - { - "field": null, - "message": "unable to find API Key to update" - } - ] + "id": 123, + "ip": "192.168.1.2", + "rdns": "o1.email.example.com", + "users": [], + "subdomain": "email", + "domain": "example.com", + "valid": true, + "legacy": false, + "a_record": { + "valid": true, + "type": "a", + "host": "o1.email.example.com", + "data": "192.168.1.2" + } } - description: Unexpected error in API call. See HTTP response body for details. queryParameters: {} - get: - displayName: Get an existing API Key - description: |- - Retrieve a single api key. - If the API Key ID does not exist an HTTP 404 will be returned. + '/{id}': + displayName: '{id}' + description: '' + uriParameters: + id: + displayName: The id of the IP whitelabel that you want to delete. + type: string + get: + displayName: Retrieve an IP whitelabel + description: |- + **This endpoint allows you to retrieve an IP whitelabel.** - ## URI Parameters + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - | Param | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key for which you are requesting information.| - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "items": { - "$ref": "#/definitions/api_key_name_id_scopes" - } - } - } - } - example: |- - { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: |- - { - "errors": [ - { - "field": null, - "message": "unable to find API Key" - } - ] - } - description: Unexpected error in API call. See HTTP response body for details. - queryParameters: {} - patch: - displayName: Update API keys - description: |- - **Update the name of an existing API Key** - - A JSON request body with a "name" property is required. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters - - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are updating.| - body: - application/json: - example: |- - { - "name": "A New Hope" - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name of the API Key." - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/api_key_name_id" - } - example: |- - { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope" - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - uriParameters: {} - get: - displayName: List all API Keys belonging to the authenticated user - description: 'The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).' - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "items": { - "$ref": "#/definitions/api_key_name_id" + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/ip_whitelabel" + } + example: |- + { + "id": 123, + "ip": "192.168.1.1", + "rdns": "o1.email.example.com", + "users": [ + { + "username": "john@example.com", + "user_id": 7 } + ], + "subdomain": "email", + "domain": "example.com", + "valid": true, + "legacy": false, + "a_record": { + "valid": true, + "type": "a", + "host": "o1.email.example.com", + "data": "192.168.1.1" } } - } - example: |- - { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" + '404': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "errors": { + "type": "array", + "description": "The errors preventing the retrieval of the IP whitelabel.", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "A message explaining why the IP whitelabel could not be found." + } + }, + "required": [ + "message" + ] + } + } }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - post: - displayName: Create API keys - description: |- - This will create a new random API Key for the user. A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. - - There is a limit of 100 API Keys on your account. + "required": [ + "errors" + ] + } + example: |- + { + "errors": [ + { + "message": "Whitelabel ip not found." + } + ] + } + queryParameters: {} + delete: + displayName: Delete an IP whitelabel + description: |- + **This endpoint allows you to delete an IP whitelabel.** - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. - body: - application/json: - example: |- - { - "name": "My API Key", - "scopes": [ - "mail.send", - "alerts.create", - "alerts.read" - ] - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name you will use to describe this API Key." - }, - "scopes": { - "type": "array", - "description": "The individual permissions that you are giving to this API Key.", - "items": { - "type": "string" - } + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} } - }, - "required": [ - "name" - ] - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "items": { - "$ref": "#/definitions/api_key_name_id" + example: '' + '404': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "errors": { + "type": "array", + "description": "The errors preventing the IP whitelabel from being deleted.", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "A message explaining why the IP whitelabel could not be deleted." + } + } + } } } } - } - example: |- - { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "name", - "message": "missing required argument" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '403': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "Cannot create more than 100 API Keys" - } - ] - } - queryParameters: {} -/user: - displayName: user - description: '' - /settings: - displayName: settings - description: '' - /enforced_tls: - displayName: enforced_tls - description: '' - uriParameters: {} - get: - displayName: Get the current Enforced TLS settings. - headers: {} - responses: {} - queryParameters: {} - patch: - displayName: Change the Enforced TLS settings - body: - application/json: - example: |- - { - "require_tls": true, - "require_valid_cert": false - } - schema: |- - { - "type": "object", - "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { - "type": "boolean" - } + example: |- + { + "errors": [ + { + "message": "Whitelabel ip not found." + } + ] } - } - headers: {} - responses: {} queryParameters: {} - /profile: - displayName: profile - description: '' - uriParameters: {} - get: - displayName: "Get a user's profile" - description: |- - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + /validate: + displayName: validate + description: '' + uriParameters: + id: + type: integer + post: + displayName: Validate an IP whitelabel + description: |- + **This endpoint allows you to validate an IP whitelabel.** - For more information about your user profile: + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "GET User Profile response", - "type": "object", - "properties": { - "address": { - "type": "string", - "description": "The user's address." + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + body: {} + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The id of the IP whitelabel." + }, + "valid": { + "type": "boolean", + "description": "Indicates if the IP whitelabel is valid.", + "enum": [ + true, + false + ] + }, + "validation_results": { + "type": "object", + "description": "The specific results of the validation.", + "properties": { + "a_record": { + "type": "object", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the IP whitelabel could be validated.", + "enum": [ + true, + false + ] + }, + "reason": { + "type": [ + "null", + "string" + ], + "description": "The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated." + } + }, + "required": [ + "valid", + "reason" + ] + } + } + } }, - "address2": { - "type": "string", - "description": "The second line of the user's address." + "required": [ + "id", + "valid", + "validation_results" + ] + } + example: |- + { + "id": 1, + "valid": true, + "validation_results": { + "a_record": { + "valid": true, + "reason": null + } + } + } + '404': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "errors": { + "type": "array", + "description": "The error messages for the failed validation.", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "A message describing why the IP could not be validated." + } + }, + "required": [ + "message" + ] + } + } }, - "city": { - "type": "string", - "description": "The user's city." - }, - "company": { - "type": "string", - "description": "The name of the user's company." - }, - "country": { - "type": "string", - "description": "The user's country." - }, - "first_name": { - "type": "string", - "description": "The user's first name." - }, - "last_name": { - "type": "string", - "description": "The user's last name." - }, - "phone": { - "type": "string", - "description": "The user's phone number." - }, - "state": { - "type": "string", - "description": "The user's state." - }, - "website": { - "type": "string", - "description": "The user's website URL." + "required": [ + "errors" + ] + } + example: |- + { + "errors": [ + { + "message": "Whitelabel ip not found." + } + ] + } + description: Unexpected error in API call. See HTTP response body for details. + '500': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "errors": { + "type": "array", + "description": "The error messages for the failed validation.", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "A message describing why the IP whitelabel could not be validated." + } + }, + "required": [ + "message" + ] + } + } }, - "zip": { - "type": "string", - "description": "The user's zip code." - } - }, - "required": [ - "address", - "city", - "company", - "country", - "first_name", - "last_name", - "phone", - "state", - "website", - "zip" - ] - } - example: |- - { - "address": "814 West Chapman Avenue", - "address2": "", - "city": "Orange", - "company": "SendGrid", - "country": "US", - "first_name": "Test", - "last_name": "User", - "phone": "555-555-5555", - "state": "CA", - "website": "http://www.sendgrid.com", - "zip": "92868" - } - '401': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - queryParameters: {} - patch: - displayName: "Update a user's profile" - description: |- - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: - - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - - It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. - body: - application/json: - example: |- - { - "first_name": "Example", - "last_name": "User", - "city": "Orange" - } - schema: |- - { - "$ref": "#/definitions/user_profile" - } - headers: - on-behalf-of: - type: string - description: "You can enter a subuser name as the value for this header, in order to update the subuser's profile." - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/user_profile" - } - example: |- - { - "address": "814 West Chapman Avenue", - "address2": "", - "city": "Orange", - "company": "SendGrid", - "country": "US", - "first_name": "Example", - "last_name": "User", - "phone": "555-555-5555", - "state": "CA", - "website": "http://www.sendgrid.com", - "zip": "92868" - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - /scheduled_sends: - displayName: scheduled_sends + "required": [ + "errors" + ] + } + example: |- + { + "errors": [ + { + "message": "internal error getting rDNS" + } + ] + } + queryParameters: {} +/ips: + displayName: ips + description: '' + /pools: + displayName: pools description: '' - '/{batch_id}': - displayName: '{batch_id}' + '/{pool_name}': + displayName: '{pool_name}' description: '' - uriParameters: {} + uriParameters: + pool_name: + type: string get: - displayName: Retrieve scheduled send - description: |- - Get cancel/paused scheduled send information for a specific batch_id. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + displayName: List the IPs in a specified pool. headers: {} responses: '200': @@ -8055,193 +6497,172 @@ documentation: application/json: schema: |- { - "type": "array", - "title": "Retrieve scheduled send response", - "items": { - "$ref": "#/definitions/user_scheduled_send_status" + "type": "object", + "properties": { + "pool_name": { + "type": "string" + }, + "ips": { + "type": "array", + "items": { + "type": "string" + } + } } } - example: |- - [ - { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", - "status": "cancel" - }, - { - "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", - "status": "pause" - } - ] - '401': + example: '' + queryParameters: {} + delete: + displayName: Delete an IP pool. + headers: {} + responses: + '204': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "type": "object", + "properties": {} } - queryParameters: - batch_id: - type: string - description: "The batch ID is the identifier that your scheduled mail sends share.\t" - pattern: '^[a-zA-Z0-9]' - patch: - displayName: Update user scheduled send information - description: |- - Update the status of a scheduled send. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - body: - application/json: - example: |- + example: '' + queryParameters: {} + /ips: + displayName: ips + description: '' + '/{ip}': + displayName: '{ip}' + description: '' + uriParameters: + ip: + type: string + delete: + displayName: Remove an IP address from a pool. + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + queryParameters: {} + uriParameters: {} + post: + displayName: Add an IP to a pool + body: + application/json: + example: |- + { + "ip": "0.0.0.0" + } + schema: |- + { + "type": "object", + "properties": { + "ip": { + "type": "string" + } + } + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "pools": { + "type": "array", + "items": { + "type": "string" + } + }, + "start_date": { + "type": "integer" + }, + "warmup": { + "type": "boolean" + } + } + } + example: |- + { + "ip": "000.00.00.0", + "pools": [ + "test1" + ], + "start_date": 1409616000, + "warmup": true + } + queryParameters: {} + put: + displayName: Update an IP pool’s name. + body: + application/json: + example: |- { - "status": "pause" + "name": "new_pool_name" } schema: |- { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status you would like the scheduled send to have.", - "enum": [ - "cancel", - "pause" - ] - } - }, - "required": [ - "status" - ] + "$ref": "#/definitions/ip_pool" } headers: {} responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "status", - "message": "status must be either cancel or pause" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/ip_pool" } example: |- { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] + "name": "new_pool_name" } - description: '"" : "batch id not found"' queryParameters: {} - delete: - displayName: Delete a cancellation or pause of a scheduled send - description: |- - Delete the cancellation/pause of a scheduled send. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] - } - queryParameters: - batch_id: - type: string - description: The batch ID with the cancel or pause that you would like to delete. - pattern: '^[a-zA-Z0-9]' uriParameters: {} + post: + displayName: Create an IP pool. + body: + application/json: + example: |- + { + "name": "marketing" + } + schema: |- + { + "type": "object", + "properties": { + "name": { + "type": "string" + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/ip_pool" + } + example: |- + { + "name": "marketing" + } + queryParameters: {} get: - displayName: Get all scheduled sends - description: |- - Get all cancel/paused scheduled send information. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + displayName: List all IP pools. headers: {} responses: '200': @@ -8251,140 +6672,267 @@ documentation: { "type": "array", "items": { - "$ref": "#/definitions/user_scheduled_send_status" + "$ref": "#/definitions/ip_pool" } } example: |- [ { - "batch_id": "YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg", - "status": "cancel" + "name": "marketing" }, { - "batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2", - "status": "cancel" + "name": "transactional" } ] - '401': + queryParameters: {} + /assigned: + displayName: assigned + description: '' + uriParameters: {} + get: + displayName: List all assigned IPs + description: Retrieve a list of your IP addresses. + headers: {} + responses: + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - post: - displayName: Cancel or pause a scheduled send - description: |- - Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will - be returned. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + "type": "array", + "title": "List all assigned IPs response", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "pools": { + "type": "array", + "items": { + "type": "string" + } + }, + "warmup": { + "type": "boolean" + }, + "start_date": { + "type": "integer" + } + } + } + } + example: |- + [ + { + "ip": "167.89.21.3", + "pools": [ + "new_test5" + ], + "warmup": true, + "start_date": 1409616000 + } + ] + queryParameters: {} + uriParameters: {} + get: + displayName: List all IPs + description: |- + See a list of all assigned and unassigned IPs. + Response includes warm up status, pools, assigned subusers, and whitelabel info. + The start_date field corresponds to when warmup started for that IP. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "subusers": { + "type": "array", + "items": { + "type": "string" + } + }, + "rdns": { + "type": "string" + }, + "pools": { + "type": "array", + "items": { + "type": "string" + } + }, + "warmup": { + "type": "boolean" + }, + "start_date": { + "type": [ + "number", + "null" + ] + }, + "whitelabeled": { + "type": "boolean" + } + } + } + } + example: |- + [ + { + "ip": "127.0.0.1", + "subusers": [ + "example_subuser1", + "example_subuser2" + ], + "rdns": "o1.em.example.com", + "pools": [], + "warmup": true, + "start_date": 1250337600, + "whitelabeled": true + }, + { + "ip": "127.0.0.1", + "subusers": [], + "pools": [], + "warmup": false, + "start_date": null, + "whitelabeled": false + } + ] + queryParameters: + ip: + type: string + description: The IP address to get + exclude_whitelabels: + type: boolean + description: Should we exclude whitelabels? + subuser: + type: string + description: The subuser you are requesting for. + limit: + type: integer + description: The number of IPs you want returned at the same time. + offset: + type: integer + description: The offset for the number of IPs that you are requesting. + /warmup: + displayName: warmup + description: '' + uriParameters: {} + post: + displayName: Add an IP to warmup. body: application/json: example: |- { - "batch_id": "YOUR_BATCH_ID", - "status": "pause" + "ip": "0.0.0.0" } schema: |- { - "title": "Cancel or pause a scheduled send request", "type": "object", "properties": { - "batch_id": { - "type": "string", - "description": "The batch ID is the identifier that your scheduled mail sends share.", - "pattern": "^[a-zA-Z0-9]" - }, - "status": { - "type": "string", - "default": "pause", - "description": "The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}", - "enum": [ - "pause", - "cancel" - ] + "ip": { + "type": "string" } - }, - "required": [ - "batch_id", - "status" - ] + } } headers: {} responses: - '201': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/user_scheduled_send_status" - } - example: '' - '400': + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} - } - example: |- - { - "errors": [ - { - "field": null, - "message": "max limit reached" - }, - { - "field": "batch_id", - "message": "invalid batch id" - }, - { - "field": "batch_id", - "message": "a status for this batch id exists, try PATCH to update the status" + "type": "array", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "start_date": { + "type": "integer" + } } - ] - } - description: |- - "" : "max limit reached" - "batch_id" : "invalid batch id" - "batch_id" : "a status for this batch id exists, try PATCH to update the status" - '401': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} + } } example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + [ + { + "ip": "0.0.0.0", + "start_date": 1409616000 + } + ] queryParameters: {} - /account: - displayName: account - description: '' - uriParameters: {} + '/{ip_address}': + displayName: '{ip_address}' + description: '' + uriParameters: + ip_address: + type: string + delete: + displayName: Remove an IP from warmup. + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + queryParameters: {} + get: + displayName: Get warmup status for a particular IP. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/ip_warmup_response" + } + example: '' + queryParameters: {} get: - displayName: "Get a user's account information." - description: "Your user's account information includes the user's account type and reputation." + displayName: Get all IPs that are currently warming up. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/ip_warmup_response" + } + example: |- + [ + { + "ip": "0.0.0.0", + "start_date": 1409616000 + } + ] + queryParameters: {} + '/{ip_address}': + displayName: '{ip_address}' + description: '' + uriParameters: + ip_address: + type: string + get: + displayName: See which pools an IP address belongs to. headers: {} responses: '200': @@ -8392,507 +6940,130 @@ documentation: application/json: schema: |- { - "title": "GET User Account response", "type": "object", "properties": { - "type": { - "type": "string", - "description": "The type of account for this user.", - "enum": [ - "free", - "paid" + "ip": { + "type": "string" + }, + "subusers": { + "type": "array", + "items": { + "type": "string" + } + }, + "rdns": { + "type": "string" + }, + "pools": { + "type": "array", + "items": { + "type": "string" + } + }, + "warmup": { + "type": "boolean" + }, + "start_date": { + "type": [ + "integer", + "null" ] }, - "reputation": { - "type": "number", - "description": "The sender reputation for this user." + "whitelabeled": { + "type": "boolean" } - }, - "required": [ - "type", - "reputation" - ] + } } example: |- { - "reputation": 100, - "type": "paid" + "ip": "000.00.00.0", + "subusers": [ + "subuser1", + "subuser2" + ], + "rdns": "o1.em.example.com", + "pools": [ + "test1" + ], + "warmup": false, + "start_date": null, + "whitelabeled": true } queryParameters: {} - /webhooks: - displayName: webhooks +/subusers: + displayName: subusers + description: '' + '/{subuser_name}': + displayName: '{subuser_name}' description: '' - /parse: - displayName: parse + /monitor: + displayName: monitor description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Gets statistics for Parse Webhook usage. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "properties": { - "metrics": { - "type": "object", - "properties": { - "received": { - "type": "number" - } - } - } - } - } - } - } - } - } - example: |- - [ - { - "date": "2015-10-11", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - } - ] - queryParameters: - limit: - type: string - offset: - type: string - aggregated_by: - type: string - start_date: - type: string - end_date: - type: string -/campaigns: - displayName: campaigns - description: '' - uriParameters: {} - get: - displayName: Get all Campaigns - description: |- - Returns campaigns in reverse order they were created (newest first). - - Returns an empty array if no campaigns exist. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - headers: {} - responses: - '200': + uriParameters: {} + post: + displayName: Create monitor settings + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. body: application/json: + example: |- + { + "email": "example@example.com", + "frequency": 50000 + } schema: |- { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "items": { - "$ref": "#/definitions/campaign_response" + "$ref": "#/definitions/monitor" + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/monitor" + } + example: |- + { + "email": "example@example.com", + "frequency": 50000 + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "User already has a monitor" } - } + ] } - } - example: |- - { - "result": [ - { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

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

Last call for winter clothes!

", - "plain_content": "Last call for winter clothes!", - "status": "Sent" - } - ] - } - queryParameters: - limit: - type: number - default: 10 - description: The number of results you would like to receive at a time. - offset: - type: number - default: '0' - description: 'The index of the first campaign to return, where 0 is the first campaign.' - '/{campaign_id}': - displayName: '{campaign_id}' - description: '' - /schedules: - displayName: schedules - description: '' - uriParameters: {} + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} delete: - displayName: Unschedule a Scheduled Campaign - description: |- - A successful unschedule will return a 204. - If the specified campaign is in the process of being sent, the only option is to cancel (a different method). - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + displayName: Delete monitor settings + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. headers: {} responses: '204': @@ -8900,10 +7071,11 @@ documentation: application/json: schema: |- { - "type": "null" + "type": "object", + "properties": {} } example: '' - '403': + '401': body: application/json: schema: |- @@ -8915,27 +7087,121 @@ documentation: "errors": [ { "field": null, - "message": "This campaign is already In Progress." - }, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ { "field": null, - "message": "This campaign is already Sent." - }, + "message": "No monitor settings for this user" + } + ] + } + queryParameters: {} + put: + displayName: Update Monitor Settings for a subuser + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + body: + application/json: + example: |- + { + "email": "example@example.com", + "frequency": 500 + } + schema: |- + { + "$ref": "#/definitions/monitor" + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/monitor" + } + example: |- + { + "email": "example@example.com", + "frequency": 500 + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "email", + "message": "Email is required" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ { "field": null, - "message": "This campaign is already Paused." - }, + "message": "authorization required" + } + ] + } + queryParameters: {} + get: + displayName: Retrieve monitor settings for a subuser + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/monitor" + } + example: |- + { + "email": "example@example.com", + "frequency": 500 + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ { "field": null, - "message": "This campaign is already Canceled." + "message": "authorization required" } ] } - description: |- - "": "This campaign is already In Progress." - "": "This campaign is already Sent." - "": "This campaign is already Paused." - "": "This campaign is already Canceled." '404': body: application/json: @@ -8948,140 +7214,157 @@ documentation: "errors": [ { "field": null, - "message": "not found" + "message": "No monitor settings for this user" } ] } - description: '"": "not found"' - queryParameters: - campaign_id: - type: string - /test: - displayName: test - description: '' - uriParameters: {} - post: - displayName: Send a Test Campaign - description: |- - To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] + queryParameters: {} + uriParameters: + subuser_name: + type: string + delete: + displayName: Delete a subuser + description: |- + This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. - For more information: + For more information about Subusers: - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + headers: {} + responses: + '204': body: application/json: - example: |- + schema: |- { - "to": "your.email@example.com" + "type": "object", + "properties": {} } + example: '' + '401': + body: + application/json: schema: |- { - "type": "object", - "properties": { - "to": { - "type": "string", - "description": "The email address that should receive the test campaign.", - "format": "email" + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" } - }, - "required": [ - "to" ] } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "Send a Test Campaign request", - "type": "object", - "properties": { - "to": { - "type": "string" - } - }, - "required": [ - "to" - ] - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - description: |- - "": "The JSON you have submitted cannot be parsed." - "to": "Please provide an email address to which the test should be sent." - "to": "You can only send tests to 10 addresses at a time." - "subject": "Please add a subject to your campaign before sending a test." - "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." - "sender_id": "Please assign a sender identity to your campaign before sending a test." - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: - campaign_id: - type: string - patch: - displayName: Update a Scheduled Campaign - description: |- - Changes the send_at time for the specified campaign. + queryParameters: {} + patch: + displayName: Enable/disable a subuser + description: |- + This endpoint allows you to enable or disable a subuser. - For more information: + For more information about Subusers: - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + body: + application/json: + example: |- + { + "disabled": false + } + schema: |- + { + "type": "object", + "properties": { + "disabled": { + "type": "boolean", + "description": "Whether or not this subuser is disabled. True means disabled, False means enabled." + } + } + } + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "invalid username" + }, + { + "message": "no fields provided" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '500': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "unable to enable user" + } + ] + } + queryParameters: {} + /ips: + displayName: ips + description: '' + uriParameters: {} + put: + displayName: Update IPs assigned to a subuser + description: "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)" body: application/json: - example: '' + example: |- + [ + "127.0.0.1" + ] schema: |- { - "title": "Update a Scheduled Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": [ - "send_at" - ] + "type": "array", + "items": { + "type": "string", + "format": "ipv4" + } } headers: {} responses: @@ -9090,58 +7373,24 @@ documentation: application/json: schema: |- { - "title": "Update a Scheduled Campaign response", "type": "object", "properties": { - "id": { - "type": "integer", - "description": "The campaign ID" - }, - "send_at": { - "type": "integer", - "description": "The unix timestamp to send the campaign." - }, - "status": { - "type": "string", - "description": "The status of the schedule." + "ips": { + "type": "array", + "items": { + "type": "string", + "format": "ipv4" + } } - }, - "required": [ - "id", - "send_at", - "status" - ] - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" + } } example: |- { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" - } + "ips": [ + "127.0.0.1" ] } - description: |- - "": "The JSON you have submitted cannot be parsed." - "send_at": "Please choose a future time for sending your campaign." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - '403': + '401': body: application/json: schema: |- @@ -9152,449 +7401,342 @@ documentation: { "errors": [ { - "field": "send_at", - "message": "You cannot update the send_at value of non-scheduled campaign." + "field": null, + "message": "authorization required" } ] } - description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' queryParameters: {} - get: - displayName: View Scheduled Time of a Campaign - description: "View the time that this campaign is scheduled to be sent. \n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)" - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "View Scheduled Time of a Campaign response", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": [ - "send_at" - ] - } - example: |- - { - "send_at": 1490778528 + uriParameters: {} + get: + displayName: List all Subusers + description: |- + This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/subuser" } - '404': - body: - application/json: - schema: |- + } + example: |- + [ { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- + "disabled": false, + "email": "example@example.com", + "id": 1234, + "username": "example_subuser" + }, { - "errors": [ - { - "field": null, - "message": "not found" - } - ] + "disabled": false, + "email": "example2@example.com", + "id": 1234, + "username": "example_subuser2" } - description: '"": "not found"' - queryParameters: {} - /now: - displayName: now - description: '' - uriParameters: {} - post: - displayName: Send a Campaign - description: |- - Send your campaign right now. Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, we don't need a body. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: '' - schema: |- - { - "type": "null" - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "title": "Send a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "status": { - "type": "string" - } - }, - "required": [ - "id", - "status" - ] - } - example: |- - { - "id": 1234, - "status": "Scheduled" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '403': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "You may only send a campaign when it is in draft mode." - } - ] - } - description: '"": "You may only send a campaign when it is in draft mode."' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: - campaign_id: - type: number - description: The id of the campaign - required: true - post: - displayName: Schedule a Campaign - description: |- - Send your campaign at a specific date and time. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + ] + '401': body: application/json: - example: |- + schema: |- { - "send_at": 1489771528 + "$ref": "#/definitions/global:ErrorResponse" } - schema: |- + example: |- { - "title": "Schedule a Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "description": "The unix timestamp for the date and time you would like your campaign to be sent out." + "errors": [ + { + "field": null, + "message": "authorization required" } - }, - "required": [ - "send_at" ] } - headers: {} - responses: - '200': + description: Unexpected error in API call. See HTTP response body for details. + queryParameters: + username: + type: string + description: The username of this subuser. + limit: + type: number + description: The number of results you would like to get in each request. + offset: + type: number + description: The number of subusers to skip. + post: + displayName: Create Subuser + description: |- + This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + body: + application/json: + example: |- + { + "username": "John@example.com", + "email": "John@example.com", + "password": "johns_password", + "ips": [ + "1.1.1.1", + "2.2.2.2" + ] + } + schema: |- + { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The username for this subuser." + }, + "email": { + "type": "string", + "description": "The email address of the subuser.", + "format": "email" + }, + "password": { + "type": "string", + "description": "The password this subuser will use when logging into SendGrid." + }, + "ips": { + "type": "array", + "description": "The IP addresses that should be assigned to this subuser.", + "items": { + "type": "string", + "format": "ipv4" + } + } + }, + "required": [ + "username", + "email", + "password", + "ips" + ] + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/subuser_post" + } + example: |- + { + "username": "example_subuser", + "user_id": 1234, + "email": "example@example.com", + "signup_session_token": "", + "authorization_token": "", + "credit_allocation": { + "type": "unlimited" + } + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "username exists" + }, + { + "message": "unable to validate IPs at this time" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '403': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "message": "you dont have permission to access this resource" + } + ] + } + '500': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: |- + { + "errors": [ + { + "message": "unable to validate IPs at this time" + } + ] + } + queryParameters: {} + /reputations: + displayName: reputations + description: '' + uriParameters: {} + get: + displayName: Retrieve Subuser Reputations + description: |- + Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will effect your sender rating. + + This endpoint allows you to request the reputations for your subusers. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "reputation": { + "type": "number", + "description": "The sender reputation this subuser has attained." + }, + "username": { + "type": "string", + "description": "The subuser that has this reputation.f" + } + }, + "required": [ + "reputation", + "username" + ] + } + } + example: |- + [ + { + "username": "example_subuser", + "reputation": 99 + }, + { + "username": "example_subuser2", + "reputation": 95.2 + } + ] + '401': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + queryParameters: + usernames: + type: string + /stats: + displayName: stats + description: '' + /sums: + displayName: sums + description: '' + uriParameters: {} + get: + displayName: ' Retrieve the totals for each email statistic metric for all subusers.' + description: |- + **This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** + + + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + headers: {} + responses: + '200': body: application/json: schema: |- { - "title": "Schedule a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID." - }, - "send_at": { - "type": "integer", - "description": "The date time you scheduled your campaign to be sent." - }, - "status": { - "type": "string", - "description": "The status of your campaign.", - "enum": [ - "Scheduled" - ] - } - }, - "required": [ - "id", - "send_at", - "status" - ] + "$ref": "#/definitions/category_stats" } example: |- { - "id": 1234, - "send_at": 1489771528, - "status": "Scheduled" + "date": "2015-10-11", + "stats": [] } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "send_at": "Please choose a future time for sending your campaign." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "The JSON you have submitted cannot be parsed." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '403': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH." - } - ] - } - description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} + queryParameters: + sort_by_direction: + type: string + description: 'The direction you want to sort. ' + enum: + - desc + - asc + start_date: + type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + limit: + type: integer + description: Limits the number of results returned per page. + offset: + type: integer + description: The point in the list to begin retrieving results from. + aggregated_by: + type: string + description: How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD. + sort_by_metric: + type: string + description: The metric that you want to sort by. Must be a single metric. uriParameters: {} - patch: - displayName: Update a Campaign + get: + displayName: Retrieve email statistics for your subusers. description: |- - Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. + **This endpoint allows you to retrieve the email statistics for the given subusers.** - For more information: + You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: |- - { - "title": "May Newsletter", - "subject": "New Products for Summer!", - "categories": [ - "summer line" - ], - "html_content": "

Check out our summer line!

", - "plain_content": "Check out our summer line!" - } - schema: |- - { - "title": "Update a Campaign request", - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the campaign." - }, - "subject": { - "type": "string", - "description": "The subject line for your campaign." - }, - "categories": { - "type": "array", - "description": "The categories you want to tag on this campaign.", - "items": { - "type": "string" - } - }, - "html_content": { - "type": "string", - "description": "The HTML content of this campaign." - }, - "plain_content": { - "type": "string", - "description": "The plain content of this campaign." - } - }, - "required": [ - "title", - "subject", - "categories", - "html_content", - "plain_content" - ] - } + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). headers: {} responses: '200': @@ -9602,245 +7744,2259 @@ documentation: application/json: schema: |- { - "title": "Update a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "title": { - "type": "string" - }, - "subject": { - "type": "string" - }, - "sender_id": { - "type": "integer", - "format": "int64" - }, - "list_ids": { - "type": "array", - "items": { - "type": "integer", - "format": "int64" - } - }, - "segment_ids": { - "type": "array", - "items": { - "type": "integer", - "format": "int64" - } - }, - "categories": { - "type": "array", - "items": { - "type": "string" - } - }, - "suppression_group_id": { - "type": "integer", - "format": "int64" - }, - "custom_unsubscribe_url": { - "type": "string" - }, - "ip_pool": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "status": { - "type": "string" - } - }, - "required": [ - "id", - "title", - "subject", - "sender_id", - "list_ids", - "segment_ids", - "categories", - "suppression_group_id", - "custom_unsubscribe_url", - "ip_pool", - "html_content", - "plain_content", - "status" - ] - } - example: |- - { - "id": 986724, - "title": "May Newsletter", - "subject": "New Products for Summer!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "summer line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our summer line!

", - "plain_content": "Check out our summer line!", - "status": "Draft" + "$ref": "#/definitions/stats" } - '400': - body: - application/json: - schema: '{}' example: |- - { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" + [ + { + "date": "2015-10-01", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-02", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-03", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-04", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-05", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-06", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-07", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-08", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-09", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-10-10", + "stats": [ + { + "type": "subuser", + "name": "Matt_subuser", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + } + ] + queryParameters: + limit: + type: integer + description: Limits the number of results returned per page. + offset: + type: integer + description: The point in the list to begin retrieving results from. + aggregated_by: + type: string + description: 'How to group the statistics. Must be either "day", "week", or "month".' + enum: + - day + - week + - month + subusers: + type: string + description: The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers. + required: true + start_date: + type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. +/api_keys: + displayName: api_keys + description: '' + '/{api_key_id}': + displayName: '{api_key_id}' + description: '' + uriParameters: + api_key_id: + type: string + patch: + displayName: Update API keys + description: |- + **Update the name of an existing API Key** + + A JSON request body with a "name" property is required. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + ## URI Parameters + + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are updating.| + body: + application/json: + example: |- + { + "name": "A New Hope" + } + schema: |- + { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The new name of the API Key." + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/api_key_name_id" + } + example: |- + { + "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", + "name": "A New Hope" + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + get: + displayName: Get an existing API Key + description: |- + Retrieve a single api key. + If the API Key ID does not exist an HTTP 404 will be returned. + + ## URI Parameters + + | Param | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key for which you are requesting information.| + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "result": { + "type": "array", + "_isOpen": true, + "items": { + "$ref": "#/definitions/api_key_name_id_scopes" + } + } + } + } + example: |- + { + "result": [ + { + "name": "API Key Name", + "api_key_id": "some-apikey-id" + }, + { + "name": "API Key Name 2", + "api_key_id": "another-apikey-id" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: |- + { + "errors": [ + { + "field": null, + "message": "unable to find API Key" + } + ] + } + description: Unexpected error in API call. See HTTP response body for details. + queryParameters: {} + put: + displayName: 'Update the name & scopes of an API Key' + description: | + A JSON request body with a "name" property is required. + Most provide the list of all the scopes an api key should have. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + body: + application/json: + example: |- + { + "name": "A New Hope", + "scopes": [ + "user.profile.read", + "user.profile.update" + ] + } + schema: |- + { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "scopes": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/api_key_name_id_scopes" + } + example: |- + { + "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", + "name": "A New Hope", + "scopes": [ + "user.profile.read", + "user.profile.update" + ] + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "expected JSON request body with 'name' property" + } + ] + } + description: Unexpected error in API call. See HTTP response body for details. + '401': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "unable to find API Key to update" + } + ] + } + description: Unexpected error in API call. See HTTP response body for details. + queryParameters: {} + delete: + displayName: Delete API keys + description: |- + **Revoke an existing API Key** + + Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + ## URI Parameters + + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are deleting.| + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "null" + } + example: '' + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "unable to find API Key" + } + ] + } + queryParameters: {} + uriParameters: {} + get: + displayName: List all API Keys belonging to the authenticated user + description: 'The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).' + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "result": { + "type": "array", + "_isOpen": true, + "items": { + "$ref": "#/definitions/api_key_name_id" + } + } + } + } + example: |- + { + "result": [ + { + "name": "API Key Name", + "api_key_id": "some-apikey-id" + }, + { + "name": "API Key Name 2", + "api_key_id": "another-apikey-id" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} +/user: + displayName: user + description: '' + /scheduled_sends: + displayName: scheduled_sends + description: '' + '/{batch_id}': + displayName: '{batch_id}' + description: '' + uriParameters: + batch_id: + type: string + patch: + displayName: Update user scheduled send information + description: |- + Update the status of a scheduled send. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + body: + application/json: + example: |- + { + "status": "pause" + } + schema: |- + { + "type": "object", + "properties": { + "status": { + "type": "string", + "description": "The status you would like the scheduled send to have.", + "enum": [ + "cancel", + "pause" + ] + } + }, + "required": [ + "status" + ] + } + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "null" + } + example: '' + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "status", + "message": "status must be either cancel or pause" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "batch id not found" + } + ] + } + description: '"" : "batch id not found"' + queryParameters: {} + delete: + displayName: Delete a cancellation or pause of a scheduled send + description: |- + Delete the cancellation/pause of a scheduled send. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "null" + } + example: '' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "batch id not found" + } + ] + } + queryParameters: {} + get: + displayName: Retrieve scheduled send + description: |- + Get cancel/paused scheduled send information for a specific batch_id. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "title": "Retrieve scheduled send response", + "items": { + "$ref": "#/definitions/user_scheduled_send_status" + } + } + example: |- + [ + { + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", + "status": "cancel" + }, + { + "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", + "status": "pause" + } + ] + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + uriParameters: {} + post: + displayName: Cancel or pause a scheduled send + description: |- + Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will + be returned. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + body: + application/json: + example: |- + { + "batch_id": "YOUR_BATCH_ID", + "status": "pause" + } + schema: |- + { + "title": "Cancel or pause a scheduled send request", + "type": "object", + "properties": { + "batch_id": { + "type": "string", + "description": "The batch ID is the identifier that your scheduled mail sends share.", + "pattern": "^[a-zA-Z0-9]" + }, + "status": { + "type": "string", + "default": "pause", + "description": "The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}", + "enum": [ + "pause", + "cancel" + ] + } + }, + "required": [ + "batch_id", + "status" + ] + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/user_scheduled_send_status" + } + example: '' + '400': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: |- + { + "errors": [ + { + "field": null, + "message": "max limit reached" + }, + { + "field": "batch_id", + "message": "invalid batch id" + }, + { + "field": "batch_id", + "message": "a status for this batch id exists, try PATCH to update the status" + } + ] + } + description: |- + "" : "max limit reached" + "batch_id" : "invalid batch id" + "batch_id" : "a status for this batch id exists, try PATCH to update the status" + '401': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + get: + displayName: Get all scheduled sends + description: |- + Get all cancel/paused scheduled send information. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/user_scheduled_send_status" + } + } + example: |- + [ + { + "batch_id": "YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg", + "status": "cancel" + }, + { + "batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2", + "status": "cancel" + } + ] + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + /account: + displayName: account + description: '' + uriParameters: {} + get: + displayName: "Get a user's account information." + description: "Your user's account information includes the user's account type and reputation." + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "title": "GET User Account response", + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of account for this user.", + "enum": [ + "free", + "paid" + ] + }, + "reputation": { + "type": "number", + "description": "The sender reputation for this user." + } + }, + "required": [ + "type", + "reputation" + ] + } + example: |- + { + "reputation": 100, + "type": "paid" + } + queryParameters: {} + /profile: + displayName: profile + description: '' + uriParameters: {} + patch: + displayName: "Update a user's profile" + description: |- + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + + It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. + body: + application/json: + example: |- + { + "first_name": "Example", + "last_name": "User", + "city": "Orange" + } + schema: |- + { + "$ref": "#/definitions/user_profile" + } + headers: + on-behalf-of: + type: string + description: "You can enter a subuser name as the value for this header, in order to update the subuser's profile." + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/user_profile" + } + example: |- + { + "address": "814 West Chapman Avenue", + "address2": "", + "city": "Orange", + "company": "SendGrid", + "country": "US", + "first_name": "Example", + "last_name": "User", + "phone": "555-555-5555", + "state": "CA", + "website": "http://www.sendgrid.com", + "zip": "92868" + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + get: + displayName: "Get a user's profile" + description: |- + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "title": "GET User Profile response", + "type": "object", + "properties": { + "address": { + "type": "string", + "description": "The user's address." + }, + "address2": { + "type": "string", + "description": "The second line of the user's address." + }, + "city": { + "type": "string", + "description": "The user's city." + }, + "company": { + "type": "string", + "description": "The name of the user's company." + }, + "country": { + "type": "string", + "description": "The user's country." + }, + "first_name": { + "type": "string", + "description": "The user's first name." + }, + "last_name": { + "type": "string", + "description": "The user's last name." + }, + "phone": { + "type": "string", + "description": "The user's phone number." + }, + "state": { + "type": "string", + "description": "The user's state." + }, + "website": { + "type": "string", + "description": "The user's website URL." + }, + "zip": { + "type": "string", + "description": "The user's zip code." + } + }, + "required": [ + "address", + "city", + "company", + "country", + "first_name", + "last_name", + "phone", + "state", + "website", + "zip" + ] + } + example: |- + { + "address": "814 West Chapman Avenue", + "address2": "", + "city": "Orange", + "company": "SendGrid", + "country": "US", + "first_name": "Test", + "last_name": "User", + "phone": "555-555-5555", + "state": "CA", + "website": "http://www.sendgrid.com", + "zip": "92868" + } + '401': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + queryParameters: {} + /settings: + displayName: settings + description: '' + /enforced_tls: + displayName: enforced_tls + description: '' + uriParameters: {} + patch: + displayName: Change the Enforced TLS settings + body: + application/json: + example: |- + { + "require_tls": true, + "require_valid_cert": false + } + schema: |- + { + "type": "object", + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } + } + } + example: |- + { + "require_tls": true, + "require_valid_cert": false + } + queryParameters: {} + get: + displayName: Get the current Enforced TLS settings. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "require_tls": { + "type": "boolean" + }, + "require_valid_cert": { + "type": "boolean" + } + } + } + example: |- + { + "require_tls": false, + "require_valid_cert": false + } + queryParameters: {} + /webhooks: + displayName: webhooks + description: '' + /parse: + displayName: parse + description: '' + /stats: + displayName: stats + description: '' + uriParameters: {} + get: + displayName: Retrieves Inbound Parse Webhook statistics. + description: |- + **This endpoint allows you to retrieve the statistics for your Parse Webhook useage.** + + SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments. + + There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date that the stats were collected." + }, + "stats": { + "type": "array", + "description": "The Parse Webhook usage statistics.", + "items": { + "type": "object", + "properties": { + "metrics": { + "type": "object", + "properties": { + "received": { + "type": "number", + "description": "The number of emails received and parsed by the Parse Webhook." + } + }, + "required": [ + "received" + ] + } + } + } + } + }, + "required": [ + "date", + "stats" + ] + } + } + example: |- + [ + { + "date": "2015-10-11", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-12", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-13", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-14", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-15", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-16", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-17", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-18", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-19", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-20", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-21", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-22", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-23", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-24", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-25", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-26", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-27", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-28", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-29", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-30", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-31", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-02", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-03", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-04", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-05", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-06", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-07", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-08", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-09", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-10", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + } + ] + queryParameters: + limit: + type: string + description: The number of statistics to return on each page. + offset: + type: string + description: The number of statistics to skip. + aggregated_by: + type: string + description: 'How you would like the statistics to by grouped. ' + enum: + - day + - week + - month + start_date: + type: string + description: The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + required: true + end_date: + type: string + description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + /settings: + displayName: settings + description: '' + uriParameters: {} + get: + displayName: Retrieve Parse API settings + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "type": "object", + "properties": { + "hostname": { + "type": "string" + }, + "url": { + "type": "string" + }, + "spam_check": { + "type": "boolean" + }, + "send_raw": { + "type": "boolean" + } + } + } + } + } + } + example: |- + { + "result": [ + { + "hostname": "example.com", + "url": "http://example.com/example", + "spam_check": false, + "send_raw": false + } + ] + } + queryParameters: {} + /event: + displayName: event + description: '' + /settings: + displayName: settings + description: '' + uriParameters: {} + patch: + displayName: Update Event Notification Settings + body: + application/json: + example: |- + { + "enabled": true, + "url": "url", + "group_resubscribe": true, + "delivered": true, + "group_unsubscribe": true, + "spamreport": true, + "bounce": true, + "deferred": true, + "unsubscribe": true, + "processed": true, + "open": true, + "click": true, + "dropped": true + } + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" + "url": { + "type": "string" }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" + "group_resubscribe": { + "type": "boolean" }, - { - "field": "sender_id", - "message": "sender_id does not exist" + "delivered": { + "type": "boolean" }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" + "group_unsubscribe": { + "type": "boolean" }, - { - "field": "list_ids", - "message": "list_ids do not all exist" + "spamreport": { + "type": "boolean" }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" + "bounce": { + "type": "boolean" }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" + "deferred": { + "type": "boolean" }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" + "unsubscribe": { + "type": "boolean" }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "processed": { + "type": "boolean" + }, + "open": { + "type": "boolean" + }, + "click": { + "type": "boolean" + }, + "dropped": { + "type": "boolean" + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "url": { + "type": "string" + }, + "group_resubscribe": { + "type": "boolean" + }, + "delivered": { + "type": "boolean" + }, + "group_unsubscribe": { + "type": "boolean" + }, + "spamreport": { + "type": "boolean" + }, + "bounce": { + "type": "boolean" + }, + "deferred": { + "type": "boolean" + }, + "unsubscribe": { + "type": "boolean" + }, + "processed": { + "type": "boolean" + }, + "open": { + "type": "boolean" + }, + "click": { + "type": "boolean" + }, + "dropped": { + "type": "boolean" + } + } + } + example: |- + { + "enabled": true, + "url": "url", + "group_resubscribe": true, + "delivered": true, + "group_unsubscribe": true, + "spamreport": true, + "bounce": true, + "deferred": true, + "unsubscribe": true, + "processed": true, + "open": true, + "click": true, + "dropped": true + } + queryParameters: {} + get: + displayName: Retrieve Event Webhook Settings + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "url": { + "type": "string" + }, + "group_resubscribe": { + "type": "boolean" + }, + "delivered": { + "type": "boolean" + }, + "group_unsubscribe": { + "type": "boolean" + }, + "spam_report": { + "type": "boolean" + }, + "bounce": { + "type": "boolean" + }, + "deferred": { + "type": "boolean" + }, + "unsubscribe": { + "type": "boolean" + }, + "processed": { + "type": "boolean" + }, + "open": { + "type": "boolean" + }, + "click": { + "type": "boolean" + }, + "dropped": { + "type": "boolean" + } + } + } + example: |- + { + "enabled": true, + "url": "url", + "group_resubscribe": true, + "delivered": true, + "group_unsubscribe": true, + "spam_report": true, + "bounce": true, + "deferred": true, + "unsubscribe": true, + "processed": true, + "open": true, + "click": true, + "dropped": true + } + queryParameters: {} + /test: + displayName: test + description: '' + uriParameters: {} + post: + displayName: 'Test Event Notification Settings ' + body: + application/json: + example: |- + { + "url": "url" + } + schema: |- + { + "type": "object", + "properties": { + "url": { + "type": "string" + } + } + } + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + queryParameters: {} +/mail_settings: + displayName: mail_settings + description: '' + /plain_content: + displayName: plain_content + description: '' + uriParameters: {} + get: + displayName: Retrieve plain content mail settings + description: |- + **This endpoint allows you to retrieve your current Plain Content mail settings.** + + The plain content setting will automatically convert any plain text emails that you send to HTML before sending. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the Plain Content mail setting is enabled." + } + } + } + example: |- + { + "enabled": false + } + queryParameters: {} + patch: + displayName: Update plain content mail settings + description: |- + **This endpoint allows you to update your current Plain Content mail settings.** + + The plain content setting will automatically convert any plain text emails that you send to HTML before sending. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "enabled": false + } + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "The new setting you would like to use for your Plain Content mail setting." + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if your Plain Content mail setting is enabled." + } + } + } + example: |- + { + "enabled": false + } + queryParameters: {} + /template: + displayName: template + description: '' + uriParameters: {} + get: + displayName: Retrieve legacy template mail settings + description: "**This endpoint allows you to retrieve your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html)." + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/mail_settings_template" + } + example: "{\n \"enabled\": false,\n \"html_content\": \"

<% body %>Example

\\n\"\n}" + queryParameters: {} + patch: + displayName: Update template mail settings + description: "**This endpoint allows you to update your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html)." + body: + application/json: + example: |- + { + "enabled": true, + "html_content": "<% body %>" + } + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if you want to enable the legacy email template mail setting." + }, + "html_content": { + "type": "string", + "description": "The new HTML content for your legacy email template." + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." + "html_content": { + "type": "string" } - ] + } } - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - '401': + example: "{\n \"enabled\": false,\n \"html_content\": \"

<% body %>Example

\\n\"\n}" + queryParameters: {} + /address_whitelist: + displayName: address_whitelist + description: '' + uriParameters: {} + get: + displayName: Retrieve address whitelist mail settings + description: |- + **This endpoint allows you to retrieve your current email address whitelist settings.** + + The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + headers: {} + responses: + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/mail_settings_address_whitelabel" } example: |- { - "errors": [ - { - "field": null, - "message": "authorization required" - } + "enabled": false, + "list": [ + "example.com" ] } - '403': + queryParameters: {} + patch: + displayName: Update address whitelist mail settings + description: |- + **This endpoint allows you to update your current email address whitelist settings.** + + The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "enabled": true, + "list": [ + "email1@example.com", + "example.com" + ] + } + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if your email address whitelist is enabled." + }, + "list": { + "type": "array", + "description": "Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.", + "items": { + "type": "string" + } + } + } + } + headers: {} + responses: + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "$ref": "#/definitions/mail_settings_address_whitelabel" } example: |- { - "errors": [ - { - "field": null, - "message": "You may only update a campaign when it is in draft mode." - } + "enabled": true, + "list": [ + "email1@example.com" ] } - description: '"": "You may only update a campaign when it is in draft mode."' - '404': + queryParameters: {} + /footer: + displayName: footer + description: '' + uriParameters: {} + get: + displayName: Retrieve footer mail settings + description: |- + **This endpoint allows you to retrieve your current Footer mail settings.** + + The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + headers: {} + responses: + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/mail_settings_footer" } example: |- { - "errors": [ - { - "field": null, - "message": "not found" - } - ] + "enabled": true, + "html_content": "Example HTML content", + "plain_content": "Example plain content" } - description: '"": "not found"' - queryParameters: - campaign_id: - type: string - get: - displayName: Get a single campaign + queryParameters: {} + patch: + displayName: Update footer mail settings description: |- - This is a place for notes and extra information about this endpoint. It is written - in Markdown - more info in the [documentation](/docs/designer#markdown). + **This endpoint allows you to update your current Footer mail settings.** - There are several special markdown helpers that automatically build tables - and html off of your endpoint definition. You can find some examples in this content. + The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - Click the "Open Editor" button above to start editing this content. + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "enabled": true, + "html_content": "...", + "plain_content": "..." + } + schema: |- + { + "$ref": "#/definitions/mail_settings_footer" + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/mail_settings_footer" + } + example: |- + { + "enabled": true, + "html_content": "Example HTML content", + "plain_content": "Example plain content" + } + queryParameters: {} + /forward_spam: + displayName: forward_spam + description: '' + uriParameters: {} + patch: + displayName: Update forward spam mail settings + description: |- + **This endpoint allows you to update your current Forward Spam mail settings.** - For more information: + Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "email": "", + "enabled": false + } + schema: |- + { + "$ref": "#/definitions/mail_settings_forward_spam" + } headers: {} responses: '200': @@ -9848,287 +10004,191 @@ documentation: application/json: schema: |- { - "$ref": "#/definitions/campaign_response" + "$ref": "#/definitions/mail_settings_forward_spam" } example: |- { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

", - "plain_content": "Check out our spring line!", - "status": "Draft" + "email": "", + "enabled": false } - '401': + queryParameters: {} + get: + displayName: Retrieve forward spam mail settings + description: |- + **This endpoint allows you to retrieve your current Forward Spam mail settings.** + + Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/mail_settings_forward_spam" + } + example: |- + { + "email": "", + "enabled": true + } + queryParameters: {} + /forward_bounce: + displayName: forward_bounce + description: '' + uriParameters: {} + patch: + displayName: Update forward bounce mail settings + description: |- + **This endpoint allows you to update your current bounce forwarding mail settings.** + + Activating this setting allows you to specify an email address to which bounce reports are forwarded. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "enabled": true, + "email": "example@example.com" + } + schema: |- + { + "$ref": "#/definitions/mail_settings_forward_bounce" + } + headers: {} + responses: + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "$ref": "#/definitions/mail_settings_forward_bounce" } - '404': - body: - application/json: - schema: '{}' example: |- { - "errors": [ - { - "field": null, - "message": "not found" - } - ] + "email": "", + "enabled": true } - description: '"": "not found"' - queryParameters: - campaign_id: - type: number - description: The id of the campaign to retrieve. - required: true - delete: - displayName: Delete a Campaign + queryParameters: {} + get: + displayName: Retrieve forward bounce mail settings description: |- - For more information: + **This endpoint allows you to retrieve your current bounce forwarding mail settings.** - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + Activating this setting allows you to specify an email address to which bounce reports are forwarded. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). headers: {} responses: - '204': + '200': body: application/json: schema: |- { - "type": "null" + "$ref": "#/definitions/mail_settings_forward_bounce" } - example: '' - '401': + example: |- + { + "enabled": false, + "email": null + } + queryParameters: {} + /spam_check: + displayName: spam_check + description: '' + uriParameters: {} + get: + displayName: Retrieve spam check mail settings + description: |- + **This endpoint allows you to retrieve your current Spam Checker mail settings.** + + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + headers: {} + responses: + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "$ref": "#/definitions/mail_settings_spam_check" } example: |- { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "enabled": false, + "max_score": 6, + "url": "http://example.com" } - '404': - body: - application/json: - schema: '{}' - example: '' - description: '"": "not found"' - queryParameters: - campaign_id: - type: string - description: The ID of the campaign to delete. - required: true - post: - displayName: Create a Campaign - description: |- - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - - Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. + queryParameters: {} + patch: + displayName: Update spam check mail settings + description: |- + **This endpoint allows you to update your current spam checker mail settings.** - For more information: + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: |- - { - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

", - "plain_content": "Check out our spring line!" - } - schema: |- - { - "$ref": "#/definitions/campaign_request" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/campaign_response" - } - example: |- - { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" - }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" - }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" - }, - { - "field": "sender_id", - "message": "sender_id does not exist" - }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" - }, - { - "field": "list_ids", - "message": "list_ids do not all exist" - }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" - }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" - }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" - }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." - } - ] - } - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." - '401': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - queryParameters: {} -/contactdb: - displayName: contactdb - description: '' - /reserved_fields: - displayName: reserved_fields + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "enabled": true, + "url": "url", + "max_score": 5 + } + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if you want the spam check mail setting to be enabled or not." + }, + "url": { + "type": "string", + "description": "The Inbound Parse URL where you would like your spam reports to be sent to." + }, + "max_score": { + "type": "integer", + "default": 5, + "description": "The new max score, or spam threshold that you would like to set for the spam checker.", + "minimum": 1, + "maximum": 10 + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/mail_settings_spam_check" + } + example: |- + { + "enabled": false, + "max_score": 6, + "url": "http://example.com" + } + queryParameters: {} + /bcc: + displayName: bcc description: '' uriParameters: {} get: - displayName: Get reserved custom fields fields. + displayName: Retrieve all BCC mail settings description: |- - List fields that are reserved and can't be used for custom field names. [GET] + **This endpoint allows you to retrieve your current BCC mail settings.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). headers: {} responses: '200': @@ -10136,438 +10196,457 @@ documentation: application/json: schema: |- { - "title": "List fields that are reserved and can't be used for custom field names. response", - "type": "object", - "properties": { - "reserved_fields": { - "type": "array", - "description": "The reserved fields that are already set up within custom fields.", - "items": { - "$ref": "#/definitions/contactdb_custom_field" - } - } - }, - "required": [ - "reserved_fields" - ] + "$ref": "#/definitions/mail_settings_bcc" } example: |- { - "reserved_fields": [ - { - "name": "first_name", - "type": "text" - }, - { - "name": "last_name", - "type": "text" - }, - { - "name": "email", - "type": "text" - }, - { - "name": "created_at", - "type": "date" - }, - { - "name": "updated_at", - "type": "date" - }, - { - "name": "last_emailed", - "type": "date" - }, - { - "name": "last_clicked", - "type": "date" - }, - { - "name": "last_opened", - "type": "date" - }, - { - "name": "my_custom_field", - "type": "text" - } - ] + "email": "example@example.com", + "enabled": false } - '401': + queryParameters: {} + patch: + displayName: Update BCC mail settings + description: |- + **This endpoint allows you to update your current BCC mail settings.** + + When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "enabled": false, + "email": "email@example.com" + } + schema: |- + { + "$ref": "#/definitions/mail_settings_patch" + } + headers: {} + responses: + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/mail_settings_patch" } example: |- { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "email": "example@example.com", + "enabled": false } queryParameters: {} - /lists: - displayName: lists + /bounce_purge: + displayName: bounce_purge + description: '' + uriParameters: {} + patch: + displayName: Update bounce purge mail settings + description: |- + **This endpoint allows you to update your current bounce purge settings.** + + This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + body: + application/json: + example: |- + { + "enabled": true, + "hard_bounces": 5, + "soft_bounces": 5 + } + schema: |- + { + "$ref": "#/definitions/mail_settings_bounce_purge" + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/mail_settings_bounce_purge" + } + example: |- + { + "enabled": false, + "hard_bounces": null, + "soft_bounces": null + } + queryParameters: {} + get: + displayName: Retrieve bounce purge mail settings + description: |- + **This endpoint allows you to retrieve your current bounce purge settings.** + + This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/mail_settings_bounce_purge" + } + example: |- + { + "enabled": false, + "soft_bounces": 1234, + "hard_bounces": null + } + queryParameters: {} + uriParameters: {} + get: + displayName: Retrieve all mail settings + description: |- + **This endpoint allows you to retrieve a list of all mail settings.** + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "result": { + "type": "array", + "description": "The list of all mail settings.", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The title of the mail setting." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if this mail setting is currently enabled." + }, + "name": { + "type": "string", + "description": "The name of the mail setting." + }, + "description": { + "type": "string", + "description": "A description of the mail setting." + } + }, + "required": [ + "title", + "enabled", + "name", + "description" + ] + } + } + }, + "required": [ + "result" + ] + } + example: |- + { + "result": [ + { + "title": "Address Whitelist", + "enabled": false, + "name": "address_whitelist", + "description": "Address / domains that should never have email suppressed." + }, + { + "title": "BCC", + "enabled": false, + "name": "bcc", + "description": "Automatically BCC an address for every e-mail sent." + }, + { + "title": "Bounce Purge", + "enabled": false, + "name": "bounce_purge", + "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days." + }, + { + "title": "Event Notification", + "enabled": true, + "name": "event_notify", + "description": "Controls notifications for events, such as bounces, clicks, and opens." + }, + { + "title": "Footer", + "enabled": false, + "name": "footer", + "description": "Allows you to add a custom footer to outgoing email." + }, + { + "title": "Forward Bounce", + "enabled": true, + "name": "forward_bounce", + "description": "Allows you to forward bounces to a specific email address." + }, + { + "title": "Forward Spam", + "enabled": false, + "name": "forward_spam", + "description": "Allows for a copy of spam reports to be forwarded to an email address." + }, + { + "title": "Legacy Email Template", + "enabled": true, + "name": "template", + "description": "Allows you to customize your outgoing HTML emails." + }, + { + "title": "Plain Content", + "enabled": false, + "name": "plain_content", + "description": "Convert your plain text emails to HTML." + }, + { + "title": "Spam Checker", + "enabled": true, + "name": "spam_check", + "description": "Check outbound messages for spam content." + } + ] + } + queryParameters: + limit: + type: integer + description: The number of settings to return. + offset: + type: integer + description: Where in the list of results to begin displaying settings. +/campaigns: + displayName: campaigns + description: '' + '/{campaign_id}': + displayName: '{campaign_id}' description: '' - '/{list_id}': - displayName: '{list_id}' + /schedules: + displayName: schedules description: '' - /recipients: - displayName: recipients - description: '' - uriParameters: {} - get: - displayName: List Recipients on a List - description: |- - List all the recipients currently on a specific list. + uriParameters: {} + get: + displayName: View Scheduled Time of a Campaign + description: "View the time that this campaign is scheduled to be sent. \n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)" + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "title": "View Scheduled Time of a Campaign response", + "type": "object", + "properties": { + "send_at": { + "type": "integer", + "format": "int64" + } + }, + "required": [ + "send_at" + ] + } + example: |- + { + "send_at": 1490778528 + } + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + description: '"": "not found"' + queryParameters: {} + patch: + displayName: Update a Scheduled Campaign + description: |- + Changes the send_at time for the specified campaign. - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_recipient" - } - } - } - } - example: |- - { - "recipients": [ - { - "created_at": 1433348344, - "custom_fields": [ - { - "id": 6234, - "name": "age", - "type": "number", - "value": null - }, - { - "id": 6233, - "name": "country", - "type": "text", - "value": null - }, - { - "id": 6235, - "name": "fname", - "type": "text", - "value": "Example" - }, - { - "id": 6239, - "name": "lname", - "type": "text", - "value": "User" - }, - { - "id": 6240, - "name": "lname", - "type": "text", - "value": null - } - ], - "email": "example@example.com", - "first_name": "Example", - "id": "ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==", - "last_clicked": 1438616117, - "last_emailed": 1438613272, - "last_name": "User", - "last_opened": 1438616109, - "updated_at": 1438616119 - } - ] - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is not a valid integer" - }, - { - "field": "page", - "message": "Returned if page is not a valid integer" - }, - { - "field": "page", - "message": "Returned if page is less than 1" - }, - { - "field": "page_size", - "message": "Returned if page_size is not a valid integer" - }, - { - "field": "page_size", - "message": "Returned if page_size is less than 1 or greater than 1000" - } - ] - } - description: |- - "list_id" : "Returned if list_id is not a valid integer" - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" - '404': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: |- - { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - } - ] - } - description: '"list_id" : "Returned if list_id does not exist"' - queryParameters: - page: - type: integer - description: Page index of first recipient to return (must be a positive integer) - page_size: - type: integer - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - list_id: - type: number - description: The ID of the list whose recipients you are requesting. - required: true - '/{recipient_id}': - displayName: '{recipient_id}' - description: '' - uriParameters: {} - post: - displayName: Add a Single Recipient to a List - description: |- - Add a recipient to a list. + For more information: - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + body: + application/json: + example: '' + schema: |- + { + "title": "Update a Scheduled Campaign request", + "type": "object", + "properties": { + "send_at": { + "type": "integer", + "format": "int64" + } + }, + "required": [ + "send_at" + ] + } + headers: {} + responses: + '200': body: application/json: + schema: |- + { + "title": "Update a Scheduled Campaign response", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The campaign ID" + }, + "send_at": { + "type": "integer", + "description": "The unix timestamp to send the campaign." + }, + "status": { + "type": "string", + "description": "The status of the schedule." + } + }, + "required": [ + "id", + "send_at", + "status" + ] + } example: '' + '400': + body: + application/json: schema: |- { - "type": "null" + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "send_at", + "message": "Please choose a future time for sending your campaign." + }, + { + "field": null, + "message": "The JSON you have submitted cannot be parsed." + }, + { + "field": null, + "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" + } + ] } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id is invalid" - } - ] - } - description: |- - "list_id" : "Returned if list_id is invalid" - "recipient_id" : "Returned if recipient_id is invalid" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id does not exist" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id does not exist" - } - ] - } - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" - queryParameters: - list_id: - type: number - description: The ID of the list to add the recipient to. - recipient_id: - type: string - description: The recipient you are adding to the list indicated. - delete: - displayName: Delete a Single Recipient from a Single List description: |- - Delete a single recipient from a list. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "no valid recipients were provided" - } - ] - } - description: |- - "list_id" : "Returned if list_id is not valid" - "recipient_id" : "Returned if recipient_id is not valid" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id does not exist" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id does not exist" - } - ] - } - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" - queryParameters: - list_id: - type: number - description: The ID of the list you are taking this recipient away from. - required: true - recipient_id: - type: number - description: The ID of the recipient to take off the list. - required: true + "": "The JSON you have submitted cannot be parsed." + "send_at": "Please choose a future time for sending your campaign." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + '403': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "send_at", + "message": "You cannot update the send_at value of non-scheduled campaign." + } + ] + } + description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + description: '"": "not found"' + queryParameters: {} + /test: + displayName: test + description: '' + uriParameters: {} post: - displayName: Add Multiple Recipients to a List + displayName: Send a Test Campaign description: |- - Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. + To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) body: application/json: example: |- - [ - "recipient_id1", - "recipient_id2" - ] + { + "to": "your.email@example.com" + } schema: |- { - "type": "array", - "items": { - "type": "string" - } + "type": "object", + "properties": { + "to": { + "type": "string", + "description": "The email address that should receive the test campaign.", + "format": "email" + } + }, + "required": [ + "to" + ] } headers: {} responses: - '201': + '204': body: application/json: schema: |- { - "type": "null" + "title": "Send a Test Campaign request", + "type": "object", + "properties": { + "to": { + "type": "string" + } + }, + "required": [ + "to" + ] } example: '' '400': @@ -10581,28 +10660,203 @@ documentation: { "errors": [ { - "field": "list_id", - "message": "list_id is invalid" + "field": "send_at", + "message": "Please choose a future time for sending your campaign." }, { - "field": "recipient_id", - "message": "no valid recipients were provided" + "field": null, + "message": "The JSON you have submitted cannot be parsed." }, { "field": null, - "message": "no recipients were added" + "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + } + ] + } + description: |- + "": "The JSON you have submitted cannot be parsed." + "to": "Please provide an email address to which the test should be sent." + "to": "You can only send tests to 10 addresses at a time." + "subject": "Please add a subject to your campaign before sending a test." + "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." + "sender_id": "Please assign a sender identity to your campaign before sending a test." + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + description: '"": "not found"' + queryParameters: {} + delete: + displayName: Unschedule a Scheduled Campaign + description: |- + A successful unschedule will return a 204. + If the specified campaign is in the process of being sent, the only option is to cancel (a different method). + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "null" + } + example: '' + '403': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "This campaign is already In Progress." + }, + { + "field": null, + "message": "This campaign is already Sent." + }, + { + "field": null, + "message": "This campaign is already Paused." + }, + { + "field": null, + "message": "This campaign is already Canceled." + } + ] + } + description: |- + "": "This campaign is already In Progress." + "": "This campaign is already Sent." + "": "This campaign is already Paused." + "": "This campaign is already Canceled." + '404': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + description: '"": "not found"' + queryParameters: {} + /now: + displayName: now + description: '' + uriParameters: {} + post: + displayName: Send a Campaign + description: |- + Send your campaign right now. Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, we don't need a body. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + body: {} + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "title": "Send a Campaign response", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64" + }, + "status": { + "type": "string" + } + }, + "required": [ + "id", + "status" + ] + } + example: |- + { + "id": 1234, + "status": "Scheduled" + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "subject", + "message": "subject can't be blank" + }, + { + "field": "sender_id", + "message": "sender_id can't be blank" + }, + { + "field": "plain_content", + "message": "plain_content can't be blank, please provide plain text or html content" + }, + { + "field": "list_id", + "message": "You must select at least 1 segment or 1 list to send to." + }, + { + "field": "unsubscribe_tag", + "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + }, + { + "field": "suppression_group_id", + "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." }, { "field": null, - "message": "request body is invalid JSON" + "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } description: |- - "list_id" : "Returned if list_id is not a valid integer" - "" : "Returned if no valid recipient ids were passed" - "" : "Returned if no recipients were added" - "" : "Returned if request body is invalid JSON" + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" '401': body: application/json: @@ -10615,10 +10869,27 @@ documentation: "errors": [ { "field": null, - "message": "authorization required" + "message": "authorization required" + } + ] + } + '403': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "You may only send a campaign when it is in draft mode." } ] } + description: '"": "You may only send a campaign when it is in draft mode."' '404': body: application/json: @@ -10630,152 +10901,80 @@ documentation: { "errors": [ { - "field": "list_id", - "message": "list_id does not exist" - }, - { - "field": "recipient_id", - "message": "recipient_id does not exist" + "field": null, + "message": "not found" } ] } - description: '"list_id": "Returned if list_id does not exist"' - queryParameters: - list_id: - type: number - description: 'The list to add your recipients to. ' - required: true - uriParameters: {} - get: - displayName: Get a single list. - description: "Get a single list. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/contactdb_list" - } - example: |- - { - "id": 1, - "name": "listname", - "recipient_count": 0 - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "invalid id" - } - ] - } - description: '"list_id" : "Returned if list_id is not valid"' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "List ID does not exist" - } - ] - } - description: '"list_id" : "Returned if list_id does not exist"' - queryParameters: - list_id: - type: number - description: The ID of the list to retrieve. - patch: - displayName: Update a List + description: '"": "not found"' + queryParameters: {} + post: + displayName: Schedule a Campaign description: |- - Update the name of a list. + Send your campaign at a specific date and time. + For more information: - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) body: application/json: example: |- { - "name": "newlistname" + "send_at": 1489771528 } schema: |- { - "title": "Update a List request", + "title": "Schedule a Campaign request", "type": "object", "properties": { - "name": { - "type": "string", - "description": "The new name for your list. " + "send_at": { + "type": "integer", + "description": "The unix timestamp for the date and time you would like your campaign to be sent out." } }, "required": [ - "name" + "send_at" ] } headers: {} responses: - '200': + '201': body: application/json: schema: |- { + "title": "Schedule a Campaign response", "type": "object", - "properties": {} - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" + "properties": { + "id": { + "type": "integer", + "description": "The campaign ID." + }, + "send_at": { + "type": "integer", + "description": "The date time you scheduled your campaign to be sent." + }, + "status": { + "type": "string", + "description": "The status of your campaign.", + "enum": [ + "Scheduled" + ] + } + }, + "required": [ + "id", + "send_at", + "status" + ] } example: |- { - "errors": [ - { - "message": "invalid id" - } - ] + "id": 1234, + "send_at": 1489771528, + "status": "Scheduled" } - description: |- - "name" : "Returned if list name is a duplicate of existing list or segment" - "name" : "Returned if list name is invalid or not provided" - "list_id" : "Returned if list_id is not valid" - "" : "Returned if request body is invalid JSON" - '404': + '400': body: application/json: schema: |- @@ -10786,33 +10985,46 @@ documentation: { "errors": [ { - "message": "List ID does not exist" + "field": "subject", + "message": "subject can't be blank" + }, + { + "field": "sender_id", + "message": "sender_id can't be blank" + }, + { + "field": "plain_content", + "message": "plain_content can't be blank, please provide plain text or html content" + }, + { + "field": "list_id", + "message": "You must select at least 1 segment or 1 list to send to." + }, + { + "field": "unsubscribe_tag", + "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + }, + { + "field": "suppression_group_id", + "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + }, + { + "field": null, + "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } - description: '"list_id" : "Returned if list_id does not exist"' - queryParameters: - list_id: - type: number - description: The ID of the list you are updating. - required: true - delete: - displayName: Delete a List - description: |- - Delete a list by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '202': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '400': + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "send_at": "Please choose a future time for sending your campaign." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "The JSON you have submitted cannot be parsed." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + '401': body: application/json: schema: |- @@ -10823,19 +11035,12 @@ documentation: { "errors": [ { - "field": "delete_contacts", - "message": "delete_contacts not a bool" - }, - { - "field": "list_id", - "message": "Returned if list_id is not valid" + "field": null, + "message": "authorization required" } ] } - description: |- - "list_id" : "Returned if list_id is not valid" - "delete_contacts" : "Returned if delete_contacts is not valid" - '401': + '403': body: application/json: schema: |- @@ -10847,10 +11052,11 @@ documentation: "errors": [ { "field": null, - "message": "authorization required" + "message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH." } ] } + description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' '404': body: application/json: @@ -10862,25 +11068,70 @@ documentation: { "errors": [ { - "message": "List not found: 5" + "field": null, + "message": "not found" } ] } - description: '"list_id" : "Returned if list_id does not exist"' - queryParameters: - delete_contacts: - type: boolean - description: Adds the ability to delete all contacts on the list in addition to deleting the list. - enum: - - true - - false - uriParameters: {} + description: '"": "not found"' + queryParameters: {} + uriParameters: + campaign_id: + type: integer + delete: + displayName: Delete a Campaign + description: |- + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + headers: {} + responses: + '204': + body: + application/json: + schema: |- + { + "type": "null" + } + example: '' + '401': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '404': + body: + application/json: + schema: '{}' + example: '' + description: '"": "not found"' + queryParameters: {} get: - displayName: List All Lists + displayName: Get a single campaign description: |- - Returns an empty list if you GET and no lists exist on your account. + This is a place for notes and extra information about this endpoint. It is written + in Markdown - more info in the [documentation](/docs/designer#markdown). - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + There are several special markdown helpers that automatically build tables + and html off of your endpoint definition. You can find some examples in this content. + + Click the "Open Editor" button above to start editing this content. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) headers: {} responses: '200': @@ -10888,99 +11139,227 @@ documentation: application/json: schema: |- { - "title": "List All Lists response", + "$ref": "#/definitions/campaign_response" + } + example: |- + { + "id": 986724, + "title": "March Newsletter", + "subject": "New Products for Spring!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 + ], + "segment_ids": [ + 110 + ], + "categories": [ + "spring line" + ], + "suppression_group_id": 42, + "custom_unsubscribe_url": "", + "ip_pool": "marketing", + "html_content": "

Check out our spring line!

", + "plain_content": "Check out our spring line!", + "status": "Draft" + } + '401': + body: + application/json: + schema: |- + { "type": "object", - "properties": { - "lists": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_list" - } + "properties": {} + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" } - }, - "required": [ - "lists" ] } + '404': + body: + application/json: + schema: '{}' example: |- { - "lists": [ + "errors": [ { - "id": 1, - "name": "the jones", - "recipient_count": 1 + "field": null, + "message": "not found" } ] } + description: '"": "not found"' queryParameters: {} - post: - displayName: Create a List + patch: + displayName: Update a Campaign description: |- - Create a list for your recipients. + Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) body: application/json: example: |- { - "name": "your list name" + "title": "May Newsletter", + "subject": "New Products for Summer!", + "categories": [ + "summer line" + ], + "html_content": "

Check out our summer line!

", + "plain_content": "Check out our summer line!" } schema: |- { - "title": "Create a List request", + "title": "Update a Campaign request", "type": "object", "properties": { - "name": { - "type": "string" + "title": { + "type": "string", + "description": "The title of the campaign." + }, + "subject": { + "type": "string", + "description": "The subject line for your campaign." + }, + "categories": { + "type": "array", + "description": "The categories you want to tag on this campaign.", + "items": { + "type": "string" + } + }, + "html_content": { + "type": "string", + "description": "The HTML content of this campaign." + }, + "plain_content": { + "type": "string", + "description": "The plain content of this campaign." } }, "required": [ - "name" + "title", + "subject", + "categories", + "html_content", + "plain_content" ] } headers: {} responses: - '201': + '200': body: application/json: schema: |- { - "$ref": "#/definitions/contactdb_list" + "$ref": "#/definitions/campaign_response" } example: |- { - "id": 1, - "name": "your list name", - "recipient_count": 0 + "id": 986724, + "title": "May Newsletter", + "subject": "New Products for Summer!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 + ], + "segment_ids": [ + 110 + ], + "categories": [ + "summer line" + ], + "suppression_group_id": 42, + "custom_unsubscribe_url": "", + "ip_pool": "marketing", + "html_content": "

Check out our summer line!

", + "plain_content": "Check out our summer line!", + "status": "Draft" } '400': body: application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } + schema: '{}' example: |- { "errors": [ { - "field": null, - "message": "Returned if request body is invalid JSON" + "field": "title", + "message": "title can't be blank" }, { - "field": "name", - "message": "Returned if list name is not a string" + "field": "title", + "message": "title is too long (maximum is 100 characters)" }, { - "field": "name", - "message": "Returned if list name is a duplicate of an existing list or segment" + "field": "categories", + "message": "categories exceeds 10 category limit" + }, + { + "field": "html_content", + "message": "html_content exceeds the 1MB limit" + }, + { + "field": "plain_content", + "message": "plain_content exceeds the 1MB limit" + }, + { + "field": "sender_id", + "message": "sender_id does not exist" + }, + { + "field": "sender_id", + "message": "sender_id is not a verified sender identity" + }, + { + "field": "list_ids", + "message": "list_ids do not all exist" + }, + { + "field": "segment_ids", + "message": "segment_ids do not all exist" + }, + { + "field": "ip_pool", + "message": "The ip pool you provided is invalid" + }, + { + "field": "suppression_group_id", + "message": "suppression_group_id does not exist" + }, + { + "field": "unsubscribes", + "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + }, + { + "field": null, + "message": "The JSON you have submitted cannot be parsed." } ] } description: |- - "name" : "Returned if list name is a duplicate of an existing list or segment" - "name" : "Returned if list name is not a string" - "" : "Returned if request body is invalid JSON" + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." '401': body: application/json: @@ -10997,42 +11376,25 @@ documentation: } ] } - queryParameters: {} - delete: - displayName: Delete Multiple lists - description: |- - Delete multiple lists. - - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '400': + '403': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": {} } example: |- { "errors": [ { "field": null, - "message": "list id was invalid" + "message": "You may only update a campaign when it is in draft mode." } ] } - description: '"id" : "Returned if all list ids are not valid"' - '401': + description: '"": "You may only update a campaign when it is in draft mode."' + '404': body: application/json: schema: |- @@ -11044,137 +11406,274 @@ documentation: "errors": [ { "field": null, - "message": "authorization required" + "message": "not found" } ] } + description: '"": "not found"' queryParameters: {} - /recipients: - displayName: recipients + uriParameters: {} + get: + displayName: Get all Campaigns + description: |- + Returns campaigns in reverse order they were created (newest first). + + Returns an empty array if no campaigns exist. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "result": { + "type": "array", + "_isOpen": true, + "items": { + "$ref": "#/definitions/campaign_response" + } + } + } + } + example: |- + { + "result": [ + { + "id": 986724, + "title": "March Newsletter", + "subject": "New Products for Spring!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 + ], + "segment_ids": [ + 110 + ], + "categories": [ + "spring line" + ], + "suppression_group_id": 42, + "custom_unsubscribe_url": "", + "ip_pool": "marketing", + "html_content": "

Check out our spring line!

", + "plain_content": "Check out our spring line!", + "status": "Draft" + }, + { + "id": 986723, + "title": "February Newsletter", + "subject": "Final Winter Product Sale!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 + ], + "segment_ids": [ + 110 + ], + "categories": [ + "winter line" + ], + "suppression_group_id": 42, + "custom_unsubscribe_url": "", + "ip_pool": "marketing", + "html_content": "

Last call for winter clothes!

", + "plain_content": "Last call for winter clothes!", + "status": "Sent" + } + ] + } + queryParameters: + limit: + type: number + description: The number of results you would like to receive at a time. + offset: + type: number + description: 'The index of the first campaign to return, where 0 is the first campaign.' + post: + displayName: Create a Campaign + description: |- + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + + + Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + body: + application/json: + example: |- + { + "title": "March Newsletter", + "subject": "New Products for Spring!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 + ], + "segment_ids": [ + 110 + ], + "categories": [ + "spring line" + ], + "suppression_group_id": 42, + "custom_unsubscribe_url": "", + "ip_pool": "marketing", + "html_content": "

Check out our spring line!

", + "plain_content": "Check out our spring line!" + } + schema: |- + { + "$ref": "#/definitions/campaign_request" + } + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/campaign_response" + } + example: |- + { + "id": 986724, + "title": "March Newsletter", + "subject": "New Products for Spring!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 + ], + "segment_ids": [ + 110 + ], + "categories": [ + "spring line" + ], + "suppression_group_id": 42, + "custom_unsubscribe_url": "", + "ip_pool": "marketing", + "html_content": "

Check out our spring line!

", + "plain_content": "Check out our spring line!", + "status": "Draft" + } + '400': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": "title", + "message": "title can't be blank" + }, + { + "field": "title", + "message": "title is too long (maximum is 100 characters)" + }, + { + "field": "categories", + "message": "categories exceeds 10 category limit" + }, + { + "field": "html_content", + "message": "html_content exceeds the 1MB limit" + }, + { + "field": "plain_content", + "message": "plain_content exceeds the 1MB limit" + }, + { + "field": "sender_id", + "message": "sender_id does not exist" + }, + { + "field": "sender_id", + "message": "sender_id is not a verified sender identity" + }, + { + "field": "list_ids", + "message": "list_ids do not all exist" + }, + { + "field": "segment_ids", + "message": "segment_ids do not all exist" + }, + { + "field": "ip_pool", + "message": "The ip pool you provided is invalid" + }, + { + "field": "suppression_group_id", + "message": "suppression_group_id does not exist" + }, + { + "field": "unsubscribes", + "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + }, + { + "field": null, + "message": "The JSON you have submitted cannot be parsed." + }, + { + "field": null, + "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + } + ] + } + description: |- + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." + "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + '401': + body: + application/json: + schema: |- + { + "type": "object", + "properties": {} + } + example: '' + queryParameters: {} +/suppression: + displayName: suppression + description: '' + /bounces: + displayName: bounces description: '' - uriParameters: {} - post: - displayName: Add recipients - description: |- - Add a recipient to your contactdb. It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - body: - application/json: - example: |- - [ - { - "email": "example@example.com", - "first_name": "", - "last_name": "User", - "age": 25 - }, - { - "email": "example2@example.com", - "first_name": "Example", - "last_name": "User", - "age": 25 - } - ] - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address of the recipient.", - "format": "email" - }, - "first_name": { - "type": "string", - "description": "The first name of the recipient." - }, - "last_name": { - "type": "string", - "description": "The last name of the recipient." - } - }, - "required": [ - "email" - ] - } - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/contactdb_recipient_response" - } - example: |- - { - "error_count": 1, - "error_indices": [ - 2 - ], - "new_count": 2, - "persisted_recipients": [ - "YUBh", - "bWlsbGVyQG1pbGxlci50ZXN0" - ], - "updated_count": 0, - "errors": [ - { - "message": "Invalid email.", - "error_indices": [ - 2 - ] - } - ] - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] - } - description: '"" : "Returned if request body is not valid json"' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - /billable_count: - displayName: billable_count + '/{email}': + displayName: '{email}' description: '' - uriParameters: {} + uriParameters: + email: + type: string get: - displayName: Get the count of billable recipients - description: |- - You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + displayName: Get a Bounce headers: {} responses: '200': @@ -11182,12 +11681,49 @@ documentation: application/json: schema: |- { - "$ref": "#/definitions/contactdb_recipient_count" + "type": "array", + "items": { + "type": "object", + "properties": { + "created": { + "type": "integer" + }, + "email": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } } example: |- + [ + { + "created": 1443651125, + "email": "bounce1@test.com", + "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", + "status": "5.1.1" + } + ] + queryParameters: {} + delete: + displayName: Delete a bounce + description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)" + headers: {} + responses: + '204': + body: + application/json: + schema: |- { - "recipient_count": 1234 + "type": "object", + "properties": {} } + example: '' '401': body: application/json: @@ -11204,46 +11740,88 @@ documentation: } ] } - queryParameters: {} - get: - displayName: "List Recipients [waiting on Bryan Adamson's response]" - description: |- - Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of - the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + queryParameters: + email_address: + type: string + description: The email address you would like to remove from the bounce list. + required: true + uriParameters: {} + delete: + displayName: Delete bounces + description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes." headers: {} responses: - '200': + '204': body: application/json: schema: |- { - "title": "List Recipients response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object" + "type": "null" + } + example: '' + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} + get: + displayName: List all bounces + description: "Bounces are messages that are returned to the server that sent it. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)" + headers: + Allow: + type: string + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "created": { + "type": "number" + }, + "email": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "status": { + "type": "string" } } - }, - "required": [ - "recipients" - ] + } } - example: '' - '400': - body: - application/json: - schema: '{}' - example: '' - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" + example: |- + [ + { + "created": 1250337600, + "email": "example@example.com", + "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", + "status": "5.1.1" + }, + { + "created": 1250337600, + "email": "example@example.com", + "reason": "550 5.1.1 : Recipient address rejected: User unknown in virtual alias table ", + "status": "5.1.1" + } + ] '401': body: application/json: @@ -11261,99 +11839,396 @@ documentation: ] } queryParameters: - page: - type: integer - description: Page index of first recipients to return (must be a positive integer) - page_size: - type: integer - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - '/{recipient_id}': - displayName: '{recipient_id}' - description: '' - uriParameters: {} - get: - displayName: Retrieve a single recipient - description: |- - Retrieve a single recipient by ID from your contact database. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- + start_time: + type: number + description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). + end_time: + type: number + description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). +/categories: + displayName: categories + description: '' + uriParameters: {} + get: + displayName: Get categories + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "category": { + "type": "string" + } + } + } + } + example: |- + [ { - "$ref": "#/definitions/contactdb_recipient" + "category": "category 1" + }, + { + "category": "category 2" } - example: '' - '400': - body: - application/json: - schema: '{}' - example: '' - description: '"recipient_id" : "Returned if recipient_id is not valid"' - '401': + ] + queryParameters: + limit: + type: integer + sort_by: + type: string + order: + type: string + category: + type: string + offset: + type: integer + /stats: + displayName: stats + description: '' + uriParameters: {} + get: + displayName: Retrieve Email Statistics for Categories + description: "**This endpoint allows you to retrieve all of your email statistics for each of your categories.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). " + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/category_stats" + } + } + example: |- + [ + { + "date": "2015-10-01", + "stats": [ + { + "type": "category", + "name": "docs", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + }, + { + "type": "category", + "name": "mattscategory", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "type": "category", + "name": "docs", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + }, + { + "type": "category", + "name": "mattscategory", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + } + ] + queryParameters: + start_date: + type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + categories: + type: string + description: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. + required: true + limit: + type: integer + description: The number of results to include. + offset: + type: integer + description: The number of results to skip. + aggregated_by: + type: string + description: 'How to group the statistics. Must be either "day", "week", or "month".' + enum: + - day + - week + - month + /sums: + displayName: sums + description: '' + uriParameters: {} + get: + displayName: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' + description: "**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). " + headers: {} + responses: + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "": { + "$ref": "#/definitions/category_stats" + } + } } example: |- { - "errors": [ + "date": "2015-01-01", + "stats": [ { - "field": null, - "message": "authorization required" + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 20, + "deferred": 0, + "delivered": 20, + "invalid_emails": 0, + "opens": 20, + "processed": 0, + "requests": 20, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 20, + "unique_opens": 20, + "unsubscribe_drops": 0, + "unsubscribes": 20 + }, + "name": "cat1", + "type": "category" + }, + { + "metrics": { + "blocks": 1, + "bounce_drops": 0, + "bounces": 0, + "clicks": 19, + "deferred": 0, + "delivered": 19, + "invalid_emails": 0, + "opens": 19, + "processed": 0, + "requests": 20, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 19, + "unique_opens": 19, + "unsubscribe_drops": 0, + "unsubscribes": 19 + }, + "name": "cat2", + "type": "category" + }, + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 5, + "deferred": 0, + "delivered": 5, + "invalid_emails": 0, + "opens": 5, + "processed": 0, + "requests": 5, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 5, + "unique_opens": 5, + "unsubscribe_drops": 0, + "unsubscribes": 5 + }, + "name": "cat3", + "type": "category" + }, + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 6, + "deferred": 0, + "delivered": 5, + "invalid_emails": 0, + "opens": 6, + "processed": 0, + "requests": 5, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 5, + "unique_opens": 5, + "unsubscribe_drops": 0, + "unsubscribes": 6 + }, + "name": "cat4", + "type": "category" + }, + { + "metrics": { + "blocks": 10, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 10, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "cat5", + "type": "category" } ] } - '404': - body: - application/json: - schema: '{}' - example: '' - description: '"recipient_id" : "Returned if record for recipient id does not exist"' queryParameters: - recipient_id: + sort_by_metric: type: string - description: The ID of the created recipient. - delete: - displayName: Delete a Recipient - description: |- - Delete a single recipient from your contact database, by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + description: The metric that you want to sort by. Must be a single metric. + sort_by_direction: + type: string + description: The direction you want to sort. + enum: + - desc + - asc + start_date: + type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + limit: + type: integer + description: Limits the number of results returned. + offset: + type: integer + description: The point in the list to begin retrieving results. + aggregated_by: + type: string + description: 'How to group the statistics. Must be either "day", "week", or "month".' + enum: + - day + - week + - month +/mail: + displayName: mail + description: '' + /batch: + displayName: batch + description: '' + '/{batch_id}': + displayName: '{batch_id}' + description: '' + uriParameters: + batch_id: + type: string + get: + displayName: Validate batch ID + description: "Validate whether or not a batch id is valid.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" headers: {} responses: - '204': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - '400': + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/mail_batch_id" } example: |- { - "errors": [ - { - "field": null, - "message": "recipient not found" - } - ] + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" } - description: '"recipient_id" : "Returned if recipient_id is not valid"' - '401': + '400': body: application/json: schema: |- @@ -11365,11 +12240,11 @@ documentation: "errors": [ { "field": null, - "message": "authorization required" + "message": "invalid batch id" } ] } - '404': + '401': body: application/json: schema: |- @@ -11381,664 +12256,535 @@ documentation: "errors": [ { "field": null, - "message": "recipient_id is not valid" + "message": "authorization required" } ] } - description: '"recipient_id" : "Returned if record for recipient id does not exist"' - queryParameters: - recipient_id: - type: string - description: The ID of the recipient to be deleted. - required: true - /lists: - displayName: lists - description: '' - uriParameters: {} - get: - displayName: Get the Lists the Recipient Is On - description: |- - Each recipient can be on many lists. This endpoint gives you the lists this recipient is associated to. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "lists": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_list" - } - } - } - } - example: |- - { - "lists": [ - { - "id": 1234, - "name": "Example list", - "recipient_count": 42 - } - ] - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "recipient ID is invalid" - } - ] - } - description: '"recipient_id" : "Returned if recipient_id is not valid"' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "recipient id not found" - } - ] - } - description: '"recipient_id" : "Returned if record for the recipient id does not exist"' - queryParameters: - recipient_id: - type: string - description: The ID of the recipient you are requesting lists for. - required: true + description: Unexpected error in API call. See HTTP response body for details. + queryParameters: {} + uriParameters: {} + post: + displayName: Create a batch ID + description: "Generate a new Batch ID to associate with scheduled sends via the mail/send endpoint.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" + body: {} + headers: {} + responses: + '201': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/mail_batch_id" + } + example: |- + { + "batch_id": "YOUR_BATCH_ID" + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} +/tracking_settings: + displayName: tracking_settings + description: '' + /click: + displayName: click + description: '' + uriParameters: {} + get: + displayName: Retrieve Click Track Settings + description: |- + **This endpoint allows you to retrieve your current click tracking setting.** + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "enable_text": { + "type": "boolean", + "description": "Indicates if click tracking is enabled for plain text emails." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if click tracking is enabled or disabled." + } + }, + "required": [ + "enable_text", + "enabled" + ] + } + example: |- + { + "enable_text": false, + "enabled": true + } + queryParameters: {} patch: - displayName: Update Recipient + displayName: Update Click Tracking Settings description: |- - Updates one or more recipients. The body is an array of recipient objects. + **This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** - It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). body: application/json: example: |- - [ - { - "email": "jones@example.com", - "last_name": "Jones", - "first_name": "Guy" - } - ] + { + "enabled": true + } schema: |- { - "type": "array", - "items": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "The setting you want to use for click tracking." + } + } + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { "type": "object", "properties": { - "email": { - "type": "string", - "format": "email" - }, - "last_name": { - "type": "string", - "description": "The last name of the recipient. This is one of the default custom fields." + "enable_text": { + "type": "boolean", + "description": "Indicates if click tracking is enabled for plain text emails" }, - "first_name": { - "type": "string", - "description": "The first name of the recipient. This is one of the default custom fields." + "enabled": { + "type": "boolean", + "description": "The new setting new setting for click tracking." } }, "required": [ - "email" + "enable_text", + "enabled" ] } + example: |- + { + "enable_text": false, + "enabled": true + } + queryParameters: {} + /subscription: + displayName: subscription + description: '' + uriParameters: {} + patch: + displayName: Update Subscription Tracking Settings + description: |- + **This endpoint allows you to update your current settings for subscription tracking.** + + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + body: + application/json: + example: |- + { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content": "html content", + "plain_content": "text content" + } + schema: |- + { + "$ref": "#/definitions/subscription_tracking_settings" + } + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/subscription_tracking_settings" + } + example: |- + { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content": "html content", + "plain_content": "text content" + } + queryParameters: {} + get: + displayName: Retrieve Subscription Tracking Settings + description: |- + **This endpoint allows you to retrieve your current settings for subscription tracking.** + + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/subscription_tracking_settings" + } + example: "{\n \"enabled\": true,\n \"html_content\": \"

Something something unsubscribe <% %> something something

\\n\",\n \"landing\": \"

subscribehere

\\n\",\n \"plain_content\": \"Something something unsubscribe <% %> something something\",\n \"replace\": \"thetag\",\n \"url\": \"\"\n}" + queryParameters: {} + uriParameters: {} + get: + displayName: Retrieve Tracking Settings + description: |- + **This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "result": { + "type": "array", + "description": "The list of all tracking settings.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the event being tracked." + }, + "title": { + "type": "string", + "description": "The title of the tracking setting." + }, + "description": { + "type": "string", + "description": "A description about the event that is being tracked." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if this tracking setting is currently enabled." + } + } + } + } + } + } + example: |- + { + "result": [ + { + "name": "open", + "title": "Open Tracking", + "description": "lorem ipsum... .", + "enabled": true + } + ] + } + queryParameters: + limit: + type: integer + description: The number of settings to return. + offset: + type: integer + description: Where in the list of results you want to begin retrieving settings. + /google_analytics: + displayName: google_analytics + description: '' + uriParameters: {} + get: + displayName: Retrieve Google Analytics Settings + description: |- + **This endpoint allows you to retrieve your current setting for Google Analytics.** + + For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). + + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/google_analytics_settings" + } + example: |- + { + "enabled": true, + "utm_campaign": "", + "utm_content": "lotsandlotsofcontent", + "utm_medium": "", + "utm_source": "", + "utm_term": "" + } + queryParameters: {} + patch: + displayName: Update Google Analytics Settings + description: |- + **This endpoint allows you to update your current setting for Google Analytics.** + + For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). + + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + body: + application/json: + example: |- + { + "enabled": true, + "utm_source": "sendgrid.com", + "utm_medium": "email", + "utm_term": "", + "utm_content": "", + "utm_campaign": "website" + } + schema: |- + { + "$ref": "#/definitions/google_analytics_settings" } headers: {} responses: - '201': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/contactdb_recipient_response" - } - example: '' - '400': + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/google_analytics_settings" } example: |- { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] + "enabled": true, + "utm_campaign": "", + "utm_content": "lotsandlotsofcontent", + "utm_medium": "", + "utm_source": "", + "utm_term": "" } - description: '"" : "Returned if request body is not valid json"' - '401': + queryParameters: {} + /open: + displayName: open + description: '' + uriParameters: {} + get: + displayName: Get Open Tracking Settings + description: |- + **This endpoint allows you to retrieve your current settings for open tracking.** + + Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + headers: {} + responses: + '200': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if open tracking is enabled." + } + }, + "required": [ + "enabled" + ] } example: |- { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "enabled": true } queryParameters: {} - /count: - displayName: count - description: '' - uriParameters: {} - get: - displayName: Get a Count of Recipients - description: |- - Get a count of the current number of recipients in your contact database. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/contactdb_recipient_count" - } - example: |- - { - "recipient_count": 1234 - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - delete: - displayName: Delete Recipient + patch: + displayName: Update Open Tracking Settings description: |- - Deletes one or more recipients. The body is a list of recipient ids to delete. + **This endpoint allows you to update your current settings for open tracking.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + body: + application/json: + example: |- + { + "enabled": true + } + schema: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "The new status that you want to set for open tracking." + } + } + } headers: {} responses: '200': - body: - application/json: - schema: '{}' - example: '' - '400': body: application/json: schema: |- { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "No recipient ids provided" + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if open tracking is enabled." } + }, + "required": [ + "enabled" ] } - description: |- - "" : "Returned if no recipients are deleted" - "" : "Returned if all of the provided recipient ids are invalid" - "" : "Returned if request body is not valid json" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } example: |- { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "enabled": true } - queryParameters: {} - /search: - displayName: search - description: '' - uriParameters: {} - get: - displayName: Get Recipients Matching Search Criteria - description: |- - Search the recipients in your contactdb. - - field_name: - - * is a variable that is substituted for your actual custom field name from your recipient. - * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) - * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert - your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to - Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through - Mon, 02 Feb 2015 23:59:59 GMT. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_recipient" - } - } - } - } - example: |- - { - "recipients": [ - { - "created_at": 1422313607, - "email": "jones@example.com", - "first_name": null, - "id": "YUBh", - "last_clicked": null, - "last_emailed": null, - "last_name": "Jones", - "last_opened": null, - "updated_at": 1422313790, - "custom_fields": [ - { - "id": 23, - "name": "pet", - "value": "Fluffy", - "type": "text" - } - ] - } - ] - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "The following parameters are not custom fields or reserved fields: [{field_name}]" - }, - { - "message": "No search params are specified" - } - ] - } - description: |- - "" : "Returned if no search params are specified" - "field" : "Returned if the provided field is invalid or does not exist" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: - '{field_name}': - type: string - /segments: - displayName: segments + queryParameters: {} +/clients: + displayName: clients + description: '' + /stats: + displayName: stats description: '' - '/{segment_id}': - displayName: '{segment_id}' - description: '' - uriParameters: {} - get: - displayName: Retrieve a Segment - description: |- - Get a single segment by ID. + uriParameters: {} + get: + displayName: Retrieve email statistics by client type. + description: |- + **This endpoint allows you to retrieve your email statistics segmented by client type.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/contactdb_segments" - } - example: |- - { - "id": 1, - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ], - "recipient_count": 1 - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "if segment_id is not valid" - } - ] - } - description: '"segment_id" : "Returned if segment_id is not valid"' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "segment_id not found" - } - ] - } - description: '"segment_id" : "Returned if segment_id does not exist"' - queryParameters: - segment_id: - type: number - description: The ID of the segment you want to request. - required: true - /recipients: - displayName: recipients - description: '' - uriParameters: {} - get: - displayName: List Recipients On a Segment - description: |- - List all of the recipients in a segment. + **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. - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "List Recipients On a Segment response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object", - "properties": {} - } - } - }, - "required": [ - "recipients" - ] - } - example: '' - '400': - body: - application/json: - schema: '{}' - example: '' - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_opens" } - example: |- + } + example: |- + [ { - "errors": [ + "date": "2014-10-01", + "stats": [ { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: '{}' - example: '' - description: |- - "segment_id" : "Returned if segment_id is not valid" - "segment_id" : "Returned if segment_id does not exist" - queryParameters: - page: - type: string - page_size: - type: string - delete: - displayName: Delete a Segment - description: |- - Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "segment_id", - "message": "Returned if segment_id is not valid" - }, - { - "field": "delete_contacts", - "message": "Returned if delete_contacts is not a valid boolean" - } - ] - } - description: |- - "segment_id" : "Returned if segment_id is not valid" - "delete_contacts" : "Returned if delete_contacts is not a valid boolean" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "segment_id", - "message": "segment_id does not exist" - } - ] - } - description: '"segment_id" : "Returned if segment_id does not exist"' - queryParameters: - delete_contacts: - type: boolean - description: True to delete all contacts matching the segment in addition to deleting the segment - patch: - displayName: Update a segment + "metrics": { + "opens": 1, + "unique_opens": 1 + }, + "name": "Gmail", + "type": "client" + } + ] + }, + { + "date": "2014-10-02", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Gmail", + "type": "client" + } + ] + } + ] + queryParameters: + start_date: + type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + aggregated_by: + type: string + description: 'How to group the statistics. Must be either "day", "week", or "month".' + enum: + - day + - week + - month + '/{client_type}': + displayName: '{client_type}' + description: '' + /stats: + displayName: stats + description: '' + uriParameters: {} + get: + displayName: Retrieve stats by a specific client type. description: |- - Update a segment. + **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - body: - application/json: - example: |- - { - "name": "The Millers", - "list_id": 5, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ] - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "list_id": { - "type": "number", - "description": "The list ID you would like this segment to be built from." - }, - "conditions": { - "type": "array", - "description": "The conditions by which this segment should be created.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" - } - } - }, - "required": [ - "name" - ] - } + **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. + + ## Available Client Types + - phone + - tablet + - webmail + - desktop + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). headers: {} responses: '200': @@ -12046,995 +12792,1241 @@ documentation: application/json: schema: |- { - "$ref": "#/definitions/contactdb_segments" - } - example: |- - { - "id": 5, - "name": "The Millers", - "list_id": 5, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ], - "recipient_count": 1 - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "request body is not valid json" - }, - { - "message": "invalid value is passed into one of the request body parameters" - }, - { - "segment_id": "segment_id", - "message": "segment id is not valid" - }, - { - "field": "field", - "message": "field and set value is not passed into the request body" - }, - { - "field": "value", - "message": "value and set value is not passed into the request body" - }, - { - "field": "operator", - "message": "operator and set value is not passed into the request body" - }, - { - "field": "and_or", - "message": "and_or is not set on more than one condition and less than all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on the only condition passed" - }, - { - "field": "and_or", - "message": "and_or and set value is not passed into the request body" - }, - { - "field": "list_id", - "message": "the list_id is not valid" - }, - { - "field": "name", - "message": "the name is not valid" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_opens" + } } example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + [ + { + "date": "2014-10-01", + "stats": [ + { + "metrics": { + "opens": 1, + "unique_opens": 1 + }, + "name": "Gmail", + "type": "client" + } + ] + }, + { + "date": "2014-10-02", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Gmail", + "type": "client" + } + ] + } + ] queryParameters: - segment_id: + start_date: type: string - description: The ID of the segment you are updating. + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + aggregated_by: + type: string + description: 'How to group the statistics. Must be either "day", "week", or "month".' + enum: + - day + - week + - month +/devices: + displayName: devices + description: '' + /stats: + displayName: stats + description: '' uriParameters: {} - post: - displayName: Create a Segment - description: "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. \n\nSegments may contain multiple condtions, joined by an \"and\" or \"or\" in the \"and_or\" field. The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." - body: - application/json: - example: |- - { - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ + get: + displayName: Retrieve email statistics by device type. + description: "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html)." + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_opens" + } + } + example: |- + [ + { + "date": "2015-10-11", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-12", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-13", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" + "date": "2015-10-14", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] }, { - "field": "last_clicked", - "value": "01/02/2015", - "operator": "gt", - "and_or": "and" + "date": "2015-10-15", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-16", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-17", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-18", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-19", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-20", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-21", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 1, + "unique_opens": 1 + } + } + ] + }, + { + "date": "2015-10-22", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-23", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-24", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-25", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-26", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 2, + "unique_opens": 2 + } + } + ] + }, + { + "date": "2015-10-27", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-28", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-29", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-30", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-31", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] }, { - "field": "clicks.campaign_identifier", - "value": "513", - "operator": "eq", - "and_or": "or" - } - ] - } - schema: |- - { - "$ref": "#/definitions/contactdb_segments" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/contactdb_segments_with_id" - } - example: |- - { - "id": 1, - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - }, - { - "field": "last_clicked", - "value": "01/02/2015", - "operator": "gt", - "and_or": "and" - }, - { - "field": "clicks.campaign_identifier", - "value": "513", - "operator": "eq", - "and_or": "or" - } - ], - "recipient_count": 0 - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "request body is not valid json" - }, - { - "message": "invalid value is passed into one of the request body parameters" - }, - { - "field": "field", - "message": "field and set value is not passed into the request body" - }, - { - "field": "value", - "message": "value and set value is not passed into the request body" - }, - { - "field": "operator", - "message": "operator and set value is not passed into the request body" - }, - { - "field": "and_or", - "message": "and_or is not set on more than one condition and less than all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on the only condition passed" - }, - { - "field": "and_or", - "message": "and_or and set value is not passed into the request body" - }, - { - "field": "list_id", - "message": "the list_id is not valid" - }, - { - "field": "name", - "message": "the name is not valid" - } - ] - } - description: |- - "name" : "Returned if the name is not valid" - "list_id" : "Returned if the list_id is not valid" - "and_or" : "Returned if and_or and set value is not passed into the request body" - "and_or" : "Returned if and_or is set on the only condition passed" - "and_or" : "Returned if and_or is set on all conditions" - "and_or" : "Returned if and_or is not set on more than one condition and less than all conditions" - "operator" : "Returned if operator and set value is not passed into the request body" - "value" : "Returned if value and set value is not passed into the request body" - "field" : "Returned if field and set value is not passed into the request body" - "" : "Returned if request body is not valid json" - "" : "Returned if invalid value is passed into one of the request body parameters" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - get: - displayName: List All Segments - description: |- - Get all your segments. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "List All Segments response", - "type": "object", - "properties": { - "segments": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_segments" + "date": "2015-11-02", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } } - } + ] }, - "required": [ - "segments" - ] - } - example: |- - { - "segments": [ - { - "id": 1234, - "name": "Age segments < 25", - "conditions": [ - { - "field": "age", - "value": "25", - "operator": "lt" + { + "date": "2015-11-03", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 } - ], - "recipient_count": 8 - }, - { - "id": 2345, - "name": "email address - gmail", - "conditions": [ - { - "field": "email", - "value": "@gmail.com", - "operator": "contains" + } + ] + }, + { + "date": "2015-11-04", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 } - ], - "recipient_count": 0 - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - /custom_fields: - displayName: custom_fields - description: '' - uriParameters: {} - post: - displayName: Create a Custom Field - description: |- - Create a custom field. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - body: - application/json: - example: |- - { - "name": "pet", - "type": "text" - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string" + } + ] }, - "type": { - "type": "string" - } - } - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - } - example: |- - { - "id": 1, - "name": "pet", - "type": "text" - } - '400': - body: - application/json: - schema: '{}' - example: |- - { - "errors": [ - { - "field": null, - "message": "Returned if request body is invalid JSON" - }, - { - "field": "type", - "message": "Returned if custom field type is invalid or not provided" - }, - { - "field": "name", - "message": "Returned if custom field name is not provided" - } - ] - } - description: |- - "" : "Returned if request body is invalid JSON" - "type" : "Returned if custom field type is invalid or not provided" - "name" : "Returned if custom field name is not provided" - queryParameters: {} - '/{custom_field_id}': - displayName: '{custom_field_id}' - description: '' - uriParameters: {} - get: - displayName: Get a Custom Field - description: |- - Get a custom field by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/contactdb_custom_field_with_id" - } - example: |- - { - "id": 1, - "name": "pet", - "type": "text" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "invalid id" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "Custom field ID does not exist" - } - ] - } - description: '"custom_field_id" : "Returned if custom_field_id does not exist"' - queryParameters: - custom_field_id: - type: number - description: The ID of the custom field you would like to retrieve - required: true - delete: - displayName: Delete a Custom Field - description: |- - Delete a custom field by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - headers: {} - responses: - '202': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "message": "Custom Field delete is processing." - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "Custom field in use by one or more segment conditions" - }, - { - "message": "Custom field ID does not exist" - } - ] - } - description: '"id" : "Returned if custom_field_id is not valid"' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "message": "Custom field ID does not exist" - } - ] - } - description: '"custom_field_id" : "Returned if custom_field_id does not exist"' - queryParameters: {} - get: - displayName: List All Custom Fields - description: "Get all custom fields. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "List All Custom Fields response", - "type": "object", - "properties": { - "custom_fields": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id" + { + "date": "2015-11-05", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-06", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-07", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } } - } + ] }, - "required": [ - "custom_fields" - ] - } - example: |- - { - "lists": [ - { - "id": 1, - "name": "the jones", - "recipient_count": 1 - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} -/templates: - displayName: templates + { + "date": "2015-11-08", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-09", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-10", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] + } + ] + queryParameters: + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. + limit: + type: integer + description: How many results to include on each page. + offset: + type: integer + description: How many results to exclude. + aggregated_by: + type: string + description: 'How to group the statistics. Must be either "day", "week", or "month".' + start_date: + type: string + description: The starting date of the statistics to retrieve. + required: true +/scopes: + displayName: scopes description: '' - '/{template_id}': - displayName: '{template_id}' + uriParameters: {} + get: + displayName: Returns a list of scopes for which this user has access. + description: "**This endpoint returns a list of all scopes that this user has access to.**\n\nAPI Keys can be used to authenticate the use of [SendGrid’s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). " + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "scopes": { + "type": "array", + "description": "The list of scopes for which this user has access.", + "uniqueItems": true, + "items": { + "type": "string" + } + } + }, + "required": [ + "scopes" + ] + } + example: |- + { + "scopes": [ + "mail.send", + "alerts.create", + "alerts.read" + ] + } + '401': + body: + application/json: + schema: |- + { + "type": "object", + "properties": { + "errors": { + "type": "array", + "description": "This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "null", + "description": "This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required." + }, + "message": { + "type": "string", + "description": "Explains why the scopes cannot be returned." + } + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + queryParameters: {} +/geo: + displayName: geo + description: '' + /stats: + displayName: stats description: '' uriParameters: {} - patch: - displayName: Edit a template. - body: - application/json: - example: |- - { - "name": "new_example_name" - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string" - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "versions": { - "type": "array", - "items": {} - } - } - } - example: |- - { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "new_example_name", - "versions": [] - } - queryParameters: {} - /versions: - displayName: versions - description: '' - '/{version_id}': - displayName: '{version_id}' - description: '' - uriParameters: {} - patch: - displayName: Edit a transactional template version. - description: |- - **This endpoint allows you to edit a version of one of your transactional templates.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + get: + displayName: Retrieve email statistics by country and state/province. + description: |- + **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + **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. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - body: - application/json: - example: |- - { - "active": 1, - "name": "updated_example_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>" - } - schema: |- - { - "type": "object", - "properties": { - "active": { - "type": "integer", - "description": "Indicates if the template version is active." - }, - "name": { - "type": "string", - "description": "The name of the template version." - }, - "html_content": { - "type": "string", - "description": "The HTML content of the template version." - }, - "plain_content": { - "type": "string", - "description": "The text/plain content of the template version." - }, - "subject": { - "type": "string", - "description": "The subject of the template version." - } + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_country" } } - headers: {} - responses: - '200': - body: - application/json: - schema: |- + example: |- + [ + { + "date": "2015-10-11", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-12", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-13", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-14", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-15", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-16", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-17", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-18", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-19", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-20", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-21", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 1, + "unique_clicks": 0, + "unique_opens": 1 + } + } + ] + }, + { + "date": "2015-10-22", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-23", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-24", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-25", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-26", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-27", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that the template version was last updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_templates::versions" + "date": "2015-10-28", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } } - }, - "required": [ - "id", - "updated_at" ] - } - example: |- + }, { - "id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f", - "template_id": "d51480ca-ca3f-465c-bc3e-ceb71d73c38d", - "active": 1, - "name": "version 1 name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-03-19 18:56:33" - } - queryParameters: {} - delete: - displayName: Delete a transactional template version. - description: |- - **This endpoint allows you to delete one of your transactional template versions.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - headers: {} - responses: - '204': - body: - application/json: - schema: |- + "date": "2015-10-29", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, { - "type": "null" - } - example: '' - queryParameters: {} - /activate: - displayName: activate - description: '' - uriParameters: {} - post: - displayName: Activate a transactional template version. - description: |- - **This endpoint allows you to activate a version of one of your templates.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - body: - application/json: - example: '' - schema: |- - { - "type": "object", - "properties": {} - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that the version was last updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_templates::versions" - } - }, - "required": [ - "id", - "updated_at" - ] - } - example: |- - { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "e3a61852-1acb-4b32-a1bc-b44b3814ab78", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-06-12 11:33:00" - } - queryParameters: {} - get: - displayName: Retrieve a specific transactional template version. - description: |- - **This endpoint allows you to retrieve a specific version of a template.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - headers: {} - responses: - '200': - body: - application/json: - schema: |- + "date": "2015-10-30", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-10-31", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-02", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-03", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-04", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that the template version was last updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_templates::versions" + "date": "2015-11-05", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } } - }, - "required": [ - "id", - "updated_at" ] - } - example: |- + }, { - "id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f", - "template_id": "d51480ca-ca3f-465c-bc3e-ceb71d73c38d", - "active": 1, - "name": "version 1 name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-03-19 18:56:33" + "date": "2015-11-06", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-07", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-08", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-09", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] + }, + { + "date": "2015-11-10", + "stats": [ + { + "type": "province", + "name": "TX", + "metrics": { + "clicks": 0, + "opens": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] } - queryParameters: {} - uriParameters: {} - post: - displayName: Create a new transactional template version. - description: | - **This endpoint allows you to create a new version of a template.** + ] + queryParameters: + limit: + type: integer + description: How many results to include on each page. + offset: + type: integer + description: How many results to exclude. + aggregated_by: + type: string + description: 'How you would like the statistics to be grouped. Must be either "day", "week", or "month".' + enum: + - day + - week + - month + start_date: + type: string + description: The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD + required: true + end_date: + type: string + description: 'The end date of the statistics to retrieve. ' + country: + type: string + description: The country you would like to see statistics for. Currently only supported for US and CA. + enum: + - US + - CA +/browsers: + displayName: browsers + description: '' + /stats: + displayName: stats + description: '' + uriParameters: {} + get: + displayName: 'Retrieve email statistics by browser. ' + description: |- + **This endpoint allows you to retrieve your email statistics segmented by browser type.** - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - body: - application/json: - example: |- - { - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>" - } - schema: |- - { - "$ref": "#/definitions/transactional_templates::versions" - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The id of the new transactional template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that this transactional template version was updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_templates::versions" - } - }, - "required": [ - "id", - "updated_at" - ] - } - example: |- - { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-03-19 18:56:33" - } - queryParameters: {} - delete: - displayName: Delete a template. + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). headers: {} responses: - '204': + '200': body: application/json: schema: |- { - "type": "object", - "properties": {} + "type": "array", + "items": { + "$ref": "#/definitions/advanced_stats_clicks" + } } - example: '' - queryParameters: {} - get: - displayName: Retrieve a single template. - headers: {} - responses: {} - queryParameters: {} + example: |- + [ + { + "date": "2014-10-01", + "stats": [ + { + "metrics": { + "clicks": 0, + "unique_clicks": 0 + }, + "name": "Chrome", + "type": "browser" + }, + { + "metrics": { + "clicks": 1, + "unique_clicks": 1 + }, + "name": "Firefox", + "type": "browser" + } + ] + }, + { + "date": "2014-10-02", + "stats": [ + { + "metrics": { + "clicks": 0, + "unique_clicks": 0 + }, + "name": "Chrome", + "type": "browser" + }, + { + "metrics": { + "clicks": 1, + "unique_clicks": 1 + }, + "name": "Firefox", + "type": "browser" + } + ] + } + ] + queryParameters: + start_date: + type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. + limit: + type: string + description: The number of results to include on each page. + offset: + type: string + description: The number of results to exclude. + aggregated_by: + type: string + description: 'How to group the stats. Must be either "day", "week", or "month".' + enum: + - day + - week + - month + browsers: + type: string + description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times. +/api_key: + displayName: api_key + description: '' uriParameters: {} post: - displayName: Create a template. + displayName: Create API keys + description: |- + This will create a new random API Key for the user. A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. + + There is a limit of 100 API Keys on your account. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. body: application/json: example: |- { - "name": "example_name" + "name": "My API Key", + "scopes": [ + "mail.send", + "alerts.create", + "alerts.read" + ] } schema: |- { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name you will use to describe this API Key." + }, + "scopes": { + "type": "array", + "description": "The individual permissions that you are giving to this API Key.", + "items": { + "type": "string" + } } - } + }, + "required": [ + "name" + ] } headers: {} responses: @@ -13045,253 +14037,190 @@ documentation: { "type": "object", "properties": { - "templates": { + "result": { "type": "array", "items": { - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "versions": { - "type": "array", - "items": { - "properties": {} - } - } - } + "$ref": "#/definitions/api_key_name_id_scopes" } } } } example: |- { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "example_name", - "versions": [] + "result": [ + { + "name": "API Key Name", + "api_key_id": "some-apikey-id" + }, + { + "name": "API Key Name 2", + "api_key_id": "another-apikey-id" + } + ] } - queryParameters: {} - get: - displayName: Retrieve all templates. - headers: {} - responses: {} - queryParameters: {} -/stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Global Stats provide all of your user’s email statistics for a given date range. - description: Global Stats provide all of your user’s email statistics for a given date range. - headers: {} - responses: - '200': + '400': body: application/json: schema: |- { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "number" - }, - "bounce_drops": { - "type": "number" - }, - "bounces": { - "type": "number" - }, - "clicks": { - "type": "number" - }, - "deferred": { - "type": "number" - }, - "delivered": { - "type": "number" - }, - "invalid_emails": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "processed": { - "type": "number" - }, - "requests": { - "type": "number" - }, - "spam_report_drops": { - "type": "number" - }, - "spam_reports": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - }, - "unsubscribe_drops": { - "type": "number" - }, - "unsubscribes": { - "type": "number" - } - } - } - } - } - } - } - } + "$ref": "#/definitions/global:ErrorResponse" } example: |- - [ - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 + { + "errors": [ + { + "field": "name", + "message": "missing required argument" + } + ] + } + '401': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + '403': + body: + application/json: + schema: |- + { + "$ref": "#/definitions/global:ErrorResponse" + } + example: |- + { + "errors": [ + { + "field": null, + "message": "Cannot create more than 100 API Keys" + } + ] + } + queryParameters: {} +/stats: + displayName: stats + description: '' + uriParameters: {} + get: + displayName: Retrieve global email statistics + description: |- + **This endpoint allows you to retrieve all of your global email statistics between a given date range.** + + Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. + headers: {} + responses: + '200': + body: + application/json: + schema: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date the stats were gathered." + }, + "stats": { + "type": "array", + "description": "The individual email activity stats.", + "items": { + "type": "object", + "properties": { + "metrics": { + "type": "object", + "properties": { + "blocks": { + "type": "integer", + "description": "The number of emails that were not allowed to be delivered by ISPs." + }, + "bounce_drops": { + "type": "integer", + "description": "The number of emails that were dropped because of a bounce." + }, + "bounces": { + "type": "integer", + "description": "The number of emails that bounced instead of being delivered." + }, + "clicks": { + "type": "integer", + "description": "The number of links that were clicked in your emails." + }, + "deferred": { + "type": "integer", + "description": "The number of emails that temporarily could not be delivered. " + }, + "delivered": { + "type": "integer", + "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." + }, + "invalid_emails": { + "type": "integer", + "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." + }, + "opens": { + "type": "integer", + "description": "The total number of times your emails were opened by recipients." + }, + "processed": { + "type": "integer", + "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." + }, + "requests": { + "type": "integer", + "description": "The number of emails that were requested to be delivered." + }, + "spam_report_drops": { + "type": "integer", + "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." + }, + "spam_reports": { + "type": "integer", + "description": "The number of recipients who marked your email as spam." + }, + "unique_clicks": { + "type": "integer", + "description": "The number of unique recipients who clicked links in your emails." + }, + "unique_opens": { + "type": "integer", + "description": "The number of unique recipients who opened your emails." + }, + "unsubscribe_drops": { + "type": "integer", + "description": "The number of emails dropped due to a recipient unsubscribing from your emails." + }, + "unsubscribes": { + "type": "integer", + "description": "The number of recipients who unsubscribed from your emails." + } + } + } + } } } + }, + "required": [ + "date", + "stats" ] - }, + } + } + example: |- + [ { - "date": "2015-11-08", + "date": "2015-11-03", "stats": [ { "metrics": { @@ -13316,7 +14245,7 @@ documentation: ] }, { - "date": "2015-11-09", + "date": "2015-11-04", "stats": [ { "metrics": { @@ -13334,2465 +14263,734 @@ documentation: "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - queryParameters: - limit: - type: string - offset: - type: string - aggregated_by: - type: string - start_date: - type: string - end_date: - type: string -/clients: - displayName: clients - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve stats by client type - description: Gets email statistics by client type. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "opens": { - "type": "integer" - }, - "unique_opens": { - "type": "integer" - } - } - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - } - } - } - } - } - example: |- - [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] - } - ] - queryParameters: - start_date: - type: string - end_date: - type: string - aggregated_by: - type: string - '/{client_type}': - displayName: '{client_type}' - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve stats by a specific client type - description: Gets email statistics by a single client type. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/stats" - } - example: '' - queryParameters: - start_date: - type: string - end_date: - type: string - aggregated_by: - type: string -/mail: - displayName: mail - description: '' - /batch: - displayName: batch - description: '' - '/{batch_id}': - displayName: '{batch_id}' - description: '' - uriParameters: {} - get: - displayName: Validate batch ID - description: "Validate whether or not a batch id is valid.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_batch_id" - } - example: |- - { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, { - "errors": [ + "date": "2015-11-05", + "stats": [ { - "field": null, - "message": "invalid batch id" + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } } ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- + }, { - "errors": [ + "date": "2015-11-06", + "stats": [ { - "field": null, - "message": "authorization required" + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } } ] - } - description: Unexpected error in API call. See HTTP response body for details. - queryParameters: - batch_id: - type: string - description: 'The ID you can use to associate multiple scheduled sends together, in case you might want to cancel or pause those sends.' - pattern: '^[A-Za-z0-9]' - required: true - uriParameters: {} - post: - displayName: Create a batch ID - description: "Generate a new Batch ID to associate with scheduled sends via the mail/send endpoint.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" - body: - application/json: - example: '' - schema: |- - { - "type": "null" - } - headers: {} - responses: - '201': - body: - application/json: - schema: "{\n \"title\": \"Generate Batch ID response\",\n \"type\": \"object\",\n \"properties\": {\n \"batch_id\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-zA-Z0-9\\\\-\\\\_]\"\n }\n },\n \"required\": [\n \"batch_id\"\n ]\n}" - example: |- - { - "batch_id": "YOUR_BATCH_ID" - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} -/suppression: - displayName: suppression - description: '' - /bounces: - displayName: bounces - description: '' - uriParameters: {} - get: - displayName: List all bounces - description: "Bounces are messages that are returned to the server that sent it. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)" - headers: - Allow: - type: string - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "number" - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string" - }, - "status": { - "type": "string" - } - } - } - } - example: |- - [ - { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", - "status": "5.1.1" - }, - { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1 : Recipient address rejected: User unknown in virtual alias table ", - "status": "5.1.1" - } - ] - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: - start_time: - type: number - description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). - end_time: - type: number - description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). - delete: - displayName: Delete bounces - description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes." - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - '/{email}': - displayName: '{email}' - description: '' - uriParameters: {} - delete: - displayName: Delete a bounce - description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)" - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - '401': - body: - application/json: - schema: |- + }, { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- + "date": "2015-11-07", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, { - "errors": [ + "date": "2015-11-08", + "stats": [ { - "field": null, - "message": "authorization required" + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } } ] - } - queryParameters: - email_address: - type: string - description: The email address you would like to remove from the bounce list. - format: email - required: true - get: - displayName: Get a Bounce - headers: {} - responses: - '200': - body: - application/json: - schema: |- + }, { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer" - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string" - }, - "status": { - "type": "string" + "date": "2015-11-09", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 } } - } + ] } - example: |- - [ - { - "created": 1443651125, - "email": "bounce1@test.com", - "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", - "status": "5.1.1" - } + ] + queryParameters: + limit: + type: integer + description: The number of results to return. + offset: + type: integer + description: The point in the list to begin retrieving results. + aggregated_by: + type: string + description: 'How to group the statistics. Must be either "day", "week", or "month".' + enum: + - day + - week + - month + start_date: + type: string + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + end_date: + type: string + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. +schemas: + - contacts: |- + { + "type": "object", + "properties": { + "address": { + "type": "string" + }, + "address2": {}, + "city": { + "type": "string" + }, + "company": { + "type": "string" + }, + "country": { + "type": "string" + }, + "email": { + "type": "string" + }, + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "phone": { + "type": "string" + }, + "state": { + "type": "string" + }, + "zip": { + "type": "string" + } + } + } + - subuser: |- + { + "title": "List all Subusers for a parent response", + "type": "object", + "properties": { + "disabled": { + "type": "boolean", + "description": "Whether or not the user is enabled or disabled." + }, + "id": { + "type": "number", + "description": "The ID of this subuser." + }, + "username": { + "type": "string", + "description": "The name by which this subuser will be referred." + }, + "email": { + "type": "string", + "description": "The email address to contact this subuser.", + "format": "email" + } + }, + "required": [ + "disabled", + "id", + "username", + "email" + ] + } + - contactdb_segments_conditions: |- + { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "value": { + "type": "string" + }, + "operator": { + "type": "string", + "enum": [ + "eq", + "ne", + "lt", + "gt", + "contains" ] - queryParameters: {} -/categories: - displayName: categories - description: '' - /stats: - displayName: stats - description: '' - /sums: - displayName: sums - description: '' - uriParameters: {} - get: - displayName: "Get sums of a category's stats [Needs: Stats object defined, has category ID?]" - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "type": "object", - "properties": {} - } - } + }, + "and_or": { + "type": "string", + "enum": [ + "and", + "or", + "" + ] + } + }, + "required": [ + "field", + "value", + "operator" + ] + } + - subuser_post: |- + { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The username of the subuser." + }, + "user_id": { + "type": "number", + "description": "The user ID for this subuser." + }, + "email": { + "type": "string", + "description": "The email address for this subuser.", + "format": "email" + }, + "signup_session_token": { + "type": "string" + }, + "authorization_token": { + "type": "string" + }, + "credit_allocation": { + "type": "object", + "properties": { + "type": { + "type": "string" } } - example: |- - { - "date": "2009-08-15", - "stats": [] + } + }, + "required": [ + "username", + "user_id", + "email" + ] + } + - contactdb_segments: |- + { + "title": "Create a Segment request", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of this segment." + }, + "list_id": { + "type": "integer", + "description": "The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list." + }, + "conditions": { + "type": "array", + "description": "The conditions for a recipient to be included in this segment.", + "items": { + "$ref": "#/definitions/contactdb_segments_conditions" } - queryParameters: - sort_by_metric: - type: string - sort_by_direction: - type: string - start_date: - type: string - required: true - end_date: - type: string - limit: - type: string - offset: - type: string - aggregated_by: - type: string - uriParameters: {} - get: - displayName: Category Stats provide all of your user’s email statistics for your categories. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string" - }, - "stats": { - "type": "array", - "items": { - "properties": { - "type": { - "type": "string" - }, - "name": { - "type": "string" - }, - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "number" - }, - "bounce_drops": { - "type": "number" - }, - "bounces": { - "type": "number" - }, - "clicks": { - "type": "number" - }, - "deferred": { - "type": "number" - }, - "delivered": { - "type": "number" - }, - "invalid_emails": { - "type": "number" - }, - "opens": { - "type": "number" - }, - "processed": { - "type": "number" - }, - "requests": { - "type": "number" - }, - "spam_report_drops": { - "type": "number" - }, - "spam_reports": { - "type": "number" - }, - "unique_clicks": { - "type": "number" - }, - "unique_opens": { - "type": "number" - }, - "unsubscribe_drops": { - "type": "number" - }, - "unsubscribes": { - "type": "number" - } - } - } - } - } - } - } - } - } - example: |- - [ - { - "date": "2015-10-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - queryParameters: - start_date: - type: string - required: true - end_date: - type: string - categories: - type: string - required: true - limit: - type: string - offset: - type: string - aggregated_by: - type: string - uriParameters: {} - get: - displayName: Get categories - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { + }, + "recipient_count": { + "type": "number", + "description": "The count of recipients in this list. This is not included on creation of segments." + } + }, + "required": [ + "name", + "conditions" + ] + } + - campaign_request: "{\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\",\n \"description\": \"The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI.\"\n },\n \"subject\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The subject of your campaign that your recipients will see.\"\n },\n \"sender_id\": {\n \"type\": [\n \"null\",\n \"integer\"\n ],\n \"description\": \"The ID of the \\\"sender\\\" identity that you have created. Your recipients will see this as the \\\"from\\\" on your marketing emails.\"\n },\n \"list_ids\": {\n \"type\": [\n \"array\",\n \"null\"\n ],\n \"description\": \"The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs\",\n \"items\": {\n \"type\": \"integer\"\n }\n },\n \"segment_ids\": {\n \"type\": [\n \"array\",\n \"null\"\n ],\n \"description\": \"The segment IDs that you are sending this list to. You can have both segment IDs and list IDs.\",\n \"items\": {\n \"type\": \"integer\"\n }\n },\n \"categories\": {\n \"type\": [\n \"array\",\n \"null\"\n ],\n \"description\": \"The categories you would like associated to this campaign.\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"suppression_group_id\": {\n \"type\": [\n \"null\",\n \"integer\"\n ],\n \"description\": \"The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.\"\n },\n \"custom_unsubscribe_url\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.\"\n },\n \"ip_pool\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The pool of IPs that you would like to send this email from.\"\n },\n \"html_content\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The HTML of your marketing email.\"\n },\n \"plain_content\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The plain text content of your emails.\"\n }\n },\n \"required\": [\n \"title\"\n ]\n}" + - contactdb_recipient_response: |- + { + "type": "object", + "properties": { + "error_count": { + "type": "number", + "default": "0", + "description": "The number of errors found while adding recipients." + }, + "error_indices": { + "type": "array", + "default": "[]", + "description": "The indices of the recipient(s) sent that caused the error. ", + "items": { + "type": "number" + } + }, + "new_count": { + "type": "number", + "default": "0", + "description": "The count of new recipients added to the contactdb." + }, + "persisted_recipients": { + "type": "array", + "default": "[]", + "description": "The recipient IDs of the recipients that already existed from this request.", + "items": { + "type": "string" + } + }, + "updated_count": { + "type": "number", + "default": "0", + "description": "The recipients who were updated from this request." + }, + "errors": { "type": "array", "items": { "type": "object", "properties": { - "category": { + "message": { "type": "string" + }, + "error_indices": { + "type": "array", + "items": { + "type": "number" + } } } } } - example: |- - [ - { - "category": "category 1" - }, - { - "category": "category 2" + }, + "required": [ + "error_count", + "new_count", + "persisted_recipients", + "updated_count" + ] + } + - transactional_template_version: |- + { + "type": "object", + "properties": { + "template_id": { + "type": "string", + "description": "The name of the original transactional template." + }, + "active": { + "type": "integer", + "description": "Set the new version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active.", + "enum": [ + 0, + 1 + ] + }, + "name": { + "type": "string", + "description": "Name of the new transactional template version." + }, + "html_content": { + "type": "string", + "description": "The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." + }, + "plain_content": { + "type": "string", + "description": "Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." + }, + "subject": { + "type": "string", + "description": "Subject of the new transactional template version. Must include <%subject%> tag." + } + }, + "required": [ + "template_id", + "active", + "name", + "html_content", + "plain_content", + "subject" + ] + } + - api_key_name_id_scopes: |- + { + "allOf": [ + { + "type": "object", + "properties": { + "scopes": { + "type": "array", + "description": "The permissions this API Key has access to.", + "items": { + "type": "string" + } + } } - ] - queryParameters: - limit: - type: string - sort_by: - type: string - order: - type: string -/browsers: - displayName: browsers - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: 'Gets email statistics by browser. ' - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": {} - } - } - example: '[]' - queryParameters: - start_date: - type: string - end_date: - type: string - limit: - type: string - offset: - type: string - aggregated_by: - type: string -/: - displayName: '' - description: '' - uriParameters: {} - get: - headers: - X-Forwarded-For: - type: string - X-Request-Start: - type: integer - From: - type: string - Total-Route-Time: - type: integer - X-Request-Id: - type: string - X-Forwarded-Proto: - type: string - Via: - type: string - Connect-Time: - type: integer - Accept: - type: string - X-Forwarded-Port: - type: integer - responses: - '200': - body: - application/json: - schema: |- + }, { + "$ref": "#/definitions/api_key_name_id" + } + ] + } + - credentials: |- + { + "type": "object", + "properties": { + "permissions": { "type": "object", "properties": { - "current_user_url": { - "type": "string" - }, - "current_user_authorizations_html_url": { - "type": "string" - }, - "authorizations_url": { - "type": "string" - }, - "code_search_url": { - "type": "string" - }, - "emails_url": { - "type": "string" - }, - "emojis_url": { - "type": "string" - }, - "events_url": { - "type": "string" - }, - "feeds_url": { - "type": "string" - }, - "followers_url": { - "type": "string" - }, - "following_url": { - "type": "string" - }, - "gists_url": { - "type": "string" - }, - "hub_url": { - "type": "string" - }, - "issue_search_url": { - "type": "string" - }, - "issues_url": { - "type": "string" - }, - "keys_url": { - "type": "string" - }, - "notifications_url": { - "type": "string" - }, - "organization_repositories_url": { - "type": "string" - }, - "organization_url": { - "type": "string" - }, - "public_gists_url": { - "type": "string" - }, - "rate_limit_url": { - "type": "string" - }, - "repository_url": { - "type": "string" - }, - "repository_search_url": { - "type": "string" - }, - "current_user_repositories_url": { - "type": "string" - }, - "starred_url": { - "type": "string" - }, - "starred_gists_url": { - "type": "string" - }, - "team_url": { - "type": "string" - }, - "user_url": { - "type": "string" - }, - "user_organizations_url": { + "api": { "type": "string" }, - "user_repositories_url": { + "mail": { "type": "string" }, - "user_search_url": { + "web": { "type": "string" } } + }, + "username": { + "type": "string" } - example: |- - { - "current_user_url": "https://api.github.com/user", - "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}", - "authorizations_url": "https://api.github.com/authorizations", - "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}", - "emails_url": "https://api.github.com/user/emails", - "emojis_url": "https://api.github.com/emojis", - "events_url": "https://api.github.com/events", - "feeds_url": "https://api.github.com/feeds", - "followers_url": "https://api.github.com/user/followers", - "following_url": "https://api.github.com/user/following{/target}", - "gists_url": "https://api.github.com/gists{/gist_id}", - "hub_url": "https://api.github.com/hub", - "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}", - "issues_url": "https://api.github.com/issues", - "keys_url": "https://api.github.com/user/keys", - "notifications_url": "https://api.github.com/notifications", - "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}", - "organization_url": "https://api.github.com/orgs/{org}", - "public_gists_url": "https://api.github.com/gists/public", - "rate_limit_url": "https://api.github.com/rate_limit", - "repository_url": "https://api.github.com/repos/{owner}/{repo}", - "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}", - "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}", - "starred_url": "https://api.github.com/user/starred{/owner}{/repo}", - "starred_gists_url": "https://api.github.com/gists/starred", - "team_url": "https://api.github.com/teams", - "user_url": "https://api.github.com/users/{user}", - "user_organizations_url": "https://api.github.com/user/orgs", - "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}", - "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}" - } - queryParameters: {} -/robots.txt: - displayName: robots.txt - description: '' - uriParameters: {} - get: - headers: - X-Forwarded-Port: - type: integer - Via: - type: string - From: - type: string - X-Request-Id: - type: string - X-Forwarded-For: - type: string - X-Request-Start: - type: integer - Total-Route-Time: - type: integer - X-Forwarded-Proto: - type: string - Connect-Time: - type: integer - responses: - '200': - body: - text/plain: - schema: |- - { - "type": "object", - "properties": {} + } + } + - partner_settings_new_relic: |- + { + "type": "object", + "properties": { + "enable_subuser_statistics": { + "type": "boolean", + "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if this setting is enabled. " + }, + "license_key": { + "type": "string", + "description": "The license key provided with your New Relic account." } - example: |- - # If you would like to crawl GitHub contact us at support@github.com. - # We also provide an extensive API: https://developer.github.com/ - - User-agent: CCBot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: coccoc - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: dotbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: duckduckbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: EtaoSpider - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Googlebot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: HTTrack - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: ia_archiver - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: IntuitGSACrawler - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Mail.RU_Bot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: msnbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Bingbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: naverbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: red-app-gsa-p-one - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: rogerbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: SandDollar - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: seznambot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Slurp - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Swiftbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Telefonica - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: teoma - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Twitterbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Yandex - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - - User-agent: * - Allow: /humans.txt - Disallow: / - queryParameters: {} -schemas: - - user_scheduled_send_status: |- + }, + "required": [ + "enabled", + "license_key" + ] + } + - suppression_group_unsubscribes: |- { + "type": "object", "allOf": [ { - "$ref": "#/definitions/mail_batch_id" + "$ref": "#/definitions/suppression_group" }, { "type": "object", - "description": "The status of the scheduled send.", + "required": [ + "unsubscribes" + ], "properties": { - "status": { - "type": "string", - "description": "The status of the scheduled send.", - "enum": [ - "cancel", - "pause" - ] + "unsubscribes": { + "type": "integer", + "description": "The unsubscribes associated with this group." } - }, - "required": [ - "status" - ] + } } ] } - - contacts: |- + - mail_settings_forward_bounce: |- { "type": "object", "properties": { - "address": { - "type": "string" - }, - "address2": {}, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, "email": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" + "type": [ + "string", + "null" + ], + "description": "The email address that you would like your bounce reports forwarded to." }, - "zip": { - "type": "string" + "enabled": { + "type": "boolean", + "description": "Indicates if the bounce forwarding mail setting is enabled." } } } - - mail_settings_footer: |- + - api_key_name_id: |- { "type": "object", "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" + "api_key_id": { + "type": "string", + "description": "The ID of your API Key. " }, - "plain_content": { - "type": "string" + "name": { + "type": "string", + "description": "The name of your API Key." } } } - - subuser: |- + - monitor: |- { - "title": "List all Subusers for a parent response", + "title": "Create monitor settings request", "type": "object", "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not the user is enabled or disabled." - }, - "id": { - "type": "number", - "description": "The ID of this subuser." - }, - "username": { - "type": "string", - "description": "The name by which this subuser will be referred." - }, "email": { "type": "string", - "description": "The email address to contact this subuser.", + "description": "The email address to send emails at the frequency specified for monitoring.", "format": "email" + }, + "frequency": { + "type": "number", + "description": "The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. " } }, "required": [ - "disabled", - "id", - "username", - "email" + "email", + "frequency" ] } - - stats: |- + - 'global:id': |- { - "type": "object", - "properties": {} + "type": "integer" } - - contactdb_recipient_count: |- + - mail_settings_template: |- { "type": "object", "properties": { - "recipient_count": { - "type": "number", - "description": "The count of recipients." + "enabled": { + "type": "boolean", + "description": "Indicates if the legacy email template setting is enabled." + }, + "html_content": { + "type": "string", + "description": "The HTML content that you want to use for your legacy email template." } - }, - "required": [ - "recipient_count" - ] + } } - - contactdb_segments_conditions: |- + - mail_settings_forward_spam: |- { "type": "object", "properties": { - "field": { - "type": "string" - }, - "value": { - "type": "string" - }, - "operator": { + "email": { "type": "string", - "enum": [ - "eq", - "ne", - "lt", - "gt", - "contains" - ] + "description": "The email address where you would like the spam reports to be forwarded." }, - "and_or": { + "enabled": { + "type": "boolean", + "description": "Indicates if the Forward Spam setting is enabled." + } + } + } + - mail_settings_patch: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the mail setting is enabled." + }, + "email": { "type": "string", - "enum": [ - "and", - "or", - "" - ] + "description": "The email address of the recipient." } - }, - "required": [ - "field", - "value", - "operator" - ] + } } - - subuser_post: |- + - mail_settings_bcc: |- { "type": "object", "properties": { - "username": { + "email": { "type": "string", - "description": "The username of the subuser." + "description": "The email address that will be sent a blind carbon copy." }, - "user_id": { - "type": "number", - "description": "The user ID for this subuser." + "enabled": { + "type": "boolean", + "description": "Indicates if the BCC setting is enabled." + } + } + } + - mail_settings_address_whitelabel: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if you have an email address whitelist enabled. " }, - "email": { - "type": "string", - "description": "The email address for this subuser.", - "format": "email" + "list": { + "type": "array", + "description": "All email address that are currently on the whitelist.", + "items": { + "type": "string" + } + } + } + } + - 'global:empty_request': |- + { + "type": "null" + } + - mail_batch_id: "{\n \"type\": \"object\",\n \"properties\": {\n \"batch_id\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-zA-Z0-9\\\\-\\\\_]\"\n }\n },\n \"required\": [\n \"batch_id\"\n ]\n}" + - campaign_response: |- + { + "allOf": [ + { + "$ref": "#/definitions/campaign_request" }, - "signup_session_token": { - "type": "string" + { + "type": "object", + "properties": { + "status": { + "type": "string", + "description": "The status of your campaign." + }, + "id": { + "type": "integer" + } + }, + "required": [ + "status" + ] + } + ] + } + - contactdb_segments_with_id: |- + { + "allOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The ID of the segment." + } + }, + "required": [ + "id" + ] }, - "authorization_token": { - "type": "string" + { + "$ref": "#/definitions/contactdb_segments" + } + ] + } + - contactdb_custom_field_with_id_value: |- + { + "allOf": [ + { + "$ref": "#/definitions/contactdb_custom_field_with_id" + }, + { + "type": "object", + "properties": { + "value": { + "type": [ + "string", + "null" + ], + "description": "The value of this recipient's custom field" + } + } + } + ], + "title": "ContactDB Custom field schema." + } + - contactdb_custom_field_with_id: |- + { + "allOf": [ + { + "$ref": "#/definitions/contactdb_custom_field" }, - "credit_allocation": { + { "type": "object", "properties": { - "type": { - "type": "string" + "id": { + "type": "number", + "description": "The ID of the custom field." } } } - }, - "required": [ - "username", - "user_id", - "email" - ] + ], + "title": "ContactDB Custom field schema with ID." } - - campaign_request: "{\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\",\n \"description\": \"The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI.\"\n },\n \"subject\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The subject of your campaign that your recipients will see.\"\n },\n \"sender_id\": {\n \"type\": [\n \"number\",\n \"null\"\n ],\n \"description\": \"The ID of the \\\"sender\\\" identity that you have created. Your recipients will see this as the \\\"from\\\" on your marketing emails.\"\n },\n \"list_ids\": {\n \"type\": [\n \"array\",\n \"null\"\n ],\n \"description\": \"The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs\",\n \"items\": {\n \"type\": \"number\"\n }\n },\n \"segment_ids\": {\n \"type\": [\n \"array\",\n \"null\"\n ],\n \"description\": \"The segment IDs that you are sending this list to. You can have both segment IDs and list IDs.\",\n \"items\": {\n \"type\": \"number\"\n }\n },\n \"categories\": {\n \"type\": [\n \"array\",\n \"null\"\n ],\n \"description\": \"The categories you would like associated to this campaign.\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"suppression_group_id\": {\n \"type\": [\n \"number\",\n \"null\"\n ],\n \"description\": \"The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.\"\n },\n \"custom_unsubscribe_url\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups.\"\n },\n \"ip_pool\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The pool of IPs that you would like to send this email from.\"\n },\n \"html_content\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The HTML of your marketing email.\"\n },\n \"plain_content\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"description\": \"The plain text content of your emails.\"\n }\n },\n \"required\": [\n \"title\"\n ]\n}" - contactdb_custom_field: |- { "title": "ContactDB Custom field schema.", @@ -15813,696 +15011,1068 @@ schemas: } } } - - contactdb_custom_field_with_id: |- + - contactdb_recipient_count: |- + { + "type": "object", + "properties": { + "recipient_count": { + "type": "number", + "description": "The count of recipients." + } + }, + "required": [ + "recipient_count" + ] + } + - user_scheduled_send_status: |- { "allOf": [ { - "$ref": "#/definitions/contactdb_custom_field" + "$ref": "#/definitions/mail_batch_id" }, { "type": "object", + "description": "The status of the scheduled send.", "properties": { - "id": { - "type": "number", - "description": "The ID of the custom field." + "status": { + "type": "string", + "description": "The status of the scheduled send.", + "enum": [ + "cancel", + "pause" + ] } - } + }, + "required": [ + "status" + ] } - ], - "title": "ContactDB Custom field schema with ID." + ] } - - contactdb_custom_field_with_id_value: |- + - contactdb_list: |- { - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field_with_id" + "title": "ContactDB lists", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The reference ID of your list." }, - { - "type": "object", - "properties": { - "value": { - "type": [ - "string", - "null" - ], - "description": "The value of this recipient's custom field" - } - } + "name": { + "type": "string", + "description": "The name of your list." + }, + "recipient_count": { + "type": "integer", + "description": "The count of recipients currently in the list." } - ], - "title": "ContactDB Custom field schema." + }, + "required": [ + "id", + "name", + "recipient_count" + ] } - - contactdb_recipient_response: |- + - user_profile: |- { "type": "object", "properties": { - "error_count": { - "type": "number", - "default": "0", - "description": "The number of errors found while adding recipients." + "address": { + "type": "string" }, - "error_indices": { - "type": "array", - "default": "[]", - "description": "The indices of the recipient(s) sent that caused the error. ", - "items": { - "type": "number" - } + "address2": { + "type": "string" }, - "new_count": { - "type": "number", - "default": "0", - "description": "The count of new recipients added to the contactdb." + "city": { + "type": "string" }, - "persisted_recipients": { + "company": { + "type": "string" + }, + "country": { + "type": "string" + }, + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "phone": { + "type": "string" + }, + "state": { + "type": "string" + }, + "website": { + "type": "string" + }, + "zip": { + "type": "string" + } + } + } + - 'global:ErrorResponse': |- + { + "type": "object", + "properties": { + "errors": { "type": "array", - "default": "[]", - "description": "The recipient IDs of the recipients that already existed from this request.", "items": { - "type": "string" + "type": "object", + "properties": { + "field": { + "type": [ + "string", + "null" + ], + "description": "The field that generated the error." + }, + "message": { + "type": "string", + "description": "The error message." + } + }, + "required": [ + "message" + ] } - }, - "updated_count": { + } + } + } + - suppression_bounce: |- + { + "type": "object", + "properties": { + "created": { "type": "number", - "default": "0", - "description": "The recipients who were updated from this request." + "description": "The unix timestamp for when the bounce record was created at SendGrid." }, - "errors": { + "email": { + "type": "string" + }, + "reason": { + "type": "string", + "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." + }, + "status": { + "type": "string", + "description": "Enhanced SMTP bounce response" + } + } + } + - contactdb_recipient: |- + { + "type": "object", + "properties": { + "recipients": { "type": "array", "items": { "type": "object", "properties": { - "message": { - "type": "string" + "id": { + "type": "string", + "description": "The ID of this recipient." }, - "error_indices": { + "created_at": { + "type": "number", + "description": "The time this record was created in your contactdb, in unixtime." + }, + "custom_fields": { "type": "array", + "description": "The custom fields assigned to this recipient and their values.", "items": { - "type": "number" + "$ref": "#/definitions/contactdb_custom_field_with_id_value" } + }, + "email": { + "type": "string", + "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", + "format": "email" + }, + "first_name": { + "type": [ + "string", + "null" + ], + "description": "The first name of this recipient. This is a default custom field that SendGrid provides." + }, + "last_name": { + "type": [ + "string", + "null" + ], + "description": "The last name of the recipient." + }, + "last_clicked": { + "type": [ + "number", + "null" + ], + "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime." + }, + "last_emailed": { + "type": [ + "number", + "null" + ], + "description": "The last time this user was emailed by one of your campaigns, in unixtime." + }, + "last_opened": { + "type": [ + "number", + "null" + ], + "description": "The last time this recipient opened an email from you, in unixtime." + }, + "updated_at": { + "type": "number", + "description": "The last update date for this recipient's record." } - } + }, + "required": [ + "email" + ] } } - }, - "required": [ - "error_count", - "new_count", - "persisted_recipients", - "updated_count" - ] + } } - - contactdb_segments: |- + - 'whitelabel::domain': |- { - "title": "Create a Segment request", "type": "object", "properties": { - "name": { - "type": "string", - "description": "The name of this segment." - }, - "list_id": { - "type": "integer", - "description": "The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list." - }, - "conditions": { - "type": "array", - "description": "The conditions for a recipient to be included in this segment.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" - } - }, - "recipient_count": { + "id": { "type": "number", - "description": "The count of recipients in this list. This is not included on creation of segments." - } - }, - "required": [ - "name", - "conditions" - ] - } - - contactdb_segments_with_id: |- - { - "allOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the segment." - } - }, - "required": [ - "id" - ] - }, - { - "$ref": "#/definitions/contactdb_segments" - } - ] - } - - 'transactional_templates::versions': |- - { - "type": "object", - "properties": { - "template_id": { - "type": "string", - "description": "The name of the original transactional template." + "description": "The ID of the domain whitelabel." }, - "active": { - "type": "integer", - "description": "Set the new version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active.", - "enum": [ - 0, - 1 - ] + "user_id": { + "type": "number", + "description": "The ID of the user that this whitelabel will be associated with." }, - "name": { + "subdomain": { "type": "string", - "description": "Name of the new transactional template version.", - "maxLength": 100 + "description": "The subdomain to use for this domain whitelabel." }, - "html_content": { + "domain": { "type": "string", - "description": "The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content.", - "maxLength": 0 + "description": "The domain that this whitelabel is being created for." }, - "plain_content": { + "username": { "type": "string", - "description": "Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content.", - "maxLength": 0 + "description": "The username that this whitelabel will be associated with." }, - "subject": { - "type": "string", - "description": "Subject of the new transactional template version. Must include <%subject%> tag." - } - }, - "required": [ - "template_id", - "active", - "name", - "html_content", - "plain_content", - "subject" - ] - } - - api_key_name_id_scopes: |- - { - "allOf": [ - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The permissions this API Key has access to.", - "items": { - "type": "string" - } - } + "ips": { + "type": "array", + "description": "The IPs to be included in the custom SPF record for this domain whitelabel.", + "items": { + "type": "object", + "properties": {} } }, - { - "$ref": "#/definitions/api_key_name_id" - } - ] - } - - campaign_response: |- - { - "allOf": [ - { - "$ref": "#/definitions/campaign_request" + "custom_spf": { + "type": "boolean", + "description": "Indicates whether this domain whitelabel will use custom SPF." }, - { + "default": { + "type": "boolean", + "description": "Indicates if this domain whitelabel is the default whitelabel." + }, + "legacy": { + "type": "boolean", + "description": "Indicates if this domain whitelabel was created using the legacy whitelabel tool." + }, + "automatic_security": { + "type": "boolean", + "description": "Indicates if this domain whitelabel uses automated security." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid whitelabel." + }, + "dns": { "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status of your campaign." - } - }, + "description": "The DNS records for this whitelabel that are used to authenticate the sending domain.", "required": [ - "status" - ] - } - ] - } - - 'global:id': |- - { - "type": "integer" - } - - mail_batch_id: "{\n \"type\": \"object\",\n \"properties\": {\n \"batch_id\": {\n \"type\": \"string\",\n \"pattern\": \"^[a-zA-Z0-9\\\\-\\\\_]\"\n }\n },\n \"required\": [\n \"batch_id\"\n ]\n}" - - 'global:empty_request': |- - { - "type": "null" - } - - downloads: |- - { - "type": "object", - "properties": { - "download_url": { - "type": "string" - } - } - } - - credentials: |- - { - "type": "object", - "properties": { - "permissions": { - "type": "object", + "mail_cname", + "dkim1", + "dkim2" + ], "properties": { - "api": { - "type": "string" + "mail_cname": { + "type": "object", + "description": "The CNAME for your sending domain that points to sendgrid.net.", + "required": [ + "valid", + "type", + "host", + "data" + ], + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid CNAME." + }, + "type": { + "type": "string", + "description": "The type of DNS record." + }, + "host": { + "type": "string", + "description": "The domain that this CNAME is created for.", + "format": "hostname" + }, + "data": { + "type": "string", + "description": "The CNAME record." + } + } }, - "mail": { - "type": "string" + "dkim1": { + "type": "object", + "description": "A DNS record.", + "required": [ + "valid", + "type", + "host", + "data" + ], + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid DNS record." + }, + "type": { + "type": "string", + "description": "The type of DNS record." + }, + "host": { + "type": "string", + "description": "The domain that this DNS record was created for." + }, + "data": { + "type": "string", + "description": "The DNS record." + } + } }, - "web": { - "type": "string" + "dkim2": { + "type": "object", + "description": "A DNS record.", + "required": [ + "valid", + "type", + "host", + "data" + ], + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid DNS record." + }, + "type": { + "type": "string", + "description": "The type of DNS record." + }, + "host": { + "type": "string", + "description": "The domain that this DNS record was created for." + }, + "data": { + "type": "string", + "description": "The DNS record." + } + } } } - }, - "username": { - "type": "string" } - } + }, + "required": [ + "id", + "user_id", + "subdomain", + "domain", + "username", + "ips", + "custom_spf", + "default", + "legacy", + "automatic_security", + "valid", + "dns" + ] } - - mail_settings_address_whitelabel: |- + - 'whitelabel:domain_spf': |- { "type": "object", "properties": { - "enabled": { - "type": "boolean" + "id": { + "type": "integer", + "description": "The ID of the domain whitelabel." }, - "list": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - - mail_settings_bcc: |- - { - "type": "object", - "properties": { - "email": { - "type": "string" + "domain": { + "type": "string", + "description": "The domain that this whitelabel was created for." }, - "enabled": { - "type": "boolean" - } - } - } - - mail_settings_bounce_purge: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" + "subdomain": { + "type": "string", + "description": "The subdomain that was used to create this whitelabel." }, - "soft_bounces": { - "type": [ - "integer", - "null" - ] + "username": { + "type": "string", + "description": "The username of the account that this whitelabel is associated with." }, - "hard_bounces": { - "type": [ - "integer", - "null" - ] - } - } - } - - 'mail_settings::patch': |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - } - - mail_settings_forward_spam: |- - { - "type": "object", - "properties": { - "email": { - "type": [ - "string", - "null" - ] + "user_id": { + "type": "integer", + "description": "The user_id of the account that this whitelabel is associated with." }, - "enabled": { - "type": "boolean" - } - } - } - - mail_settings_spam_check: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" + "ips": { + "type": "array", + "description": "The IP addresses that are included in the SPF record for this whitelabel.", + "items": {} }, - "max_score": { - "type": "number" + "custom_spf": { + "type": "boolean", + "description": "Indicates if this whitelabel uses custom SPF." }, - "url": { - "type": "string" - } - } - } - - mail_settings_template: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" + "default": { + "type": "boolean", + "description": "Indicates if this is the default whitelabel." }, - "html_content": { - "type": "string" - } - } - } - - partner_settings_new_relic: |- - { - "type": "object", - "properties": { - "enable_subuser_statistics": { - "type": "boolean" + "legacy": { + "type": "boolean", + "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." }, - "enabled": { - "type": "boolean" + "automatic_security": { + "type": "boolean", + "description": "Indicates if this whitelabel uses automated security." }, - "license_key": { - "type": "string" + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid whitelabel." + }, + "dns": { + "type": "object", + "description": "The DNS records for this whitelabel.", + "required": [ + "mail_server", + "subdomain_spf", + "domain_spf", + "dkim" + ], + "properties": { + "mail_server": { + "type": "object", + "description": "Designates which mail server is responsible for accepting messages from a domain.", + "required": [ + "host", + "type", + "data", + "valid" + ], + "properties": { + "host": { + "type": "string", + "description": "The domain sending the messages." + }, + "type": { + "type": "string", + "description": "They type of DNS record." + }, + "data": { + "type": "string", + "description": "The mail server responsible for accepting messages from the sending domain." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid DNS record." + } + } + }, + "subdomain_spf": { + "type": "object", + "description": "The SPF record for the subdomain used to create this whitelabel.", + "required": [ + "host", + "type", + "data", + "valid" + ], + "properties": { + "host": { + "type": "string", + "description": "The domain that this SPF record will be used to authenticate." + }, + "type": { + "type": "string", + "description": "The type of data in the SPF record." + }, + "data": { + "type": "string", + "description": "The SPF record." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid SPF record." + } + } + }, + "domain_spf": { + "type": "object", + "description": "The SPF record for the root domain.", + "required": [ + "host", + "type", + "data", + "valid" + ], + "properties": { + "host": { + "type": "string", + "description": "The root domain that this SPF record will be used to authenticate." + }, + "type": { + "type": "string", + "description": "The type of data in the SPF record." + }, + "data": { + "type": "string", + "description": "The SPF record." + }, + "valid": { + "type": "boolean", + "description": "Indicates if the SPF record is valid." + } + } + }, + "dkim": { + "type": "object", + "description": "The DKIM record for messages sent using this whitelabel.", + "required": [ + "host", + "type", + "data", + "valid" + ], + "properties": { + "host": { + "type": "string", + "description": "The DNS labels for the DKIM signature." + }, + "type": { + "type": "string", + "description": "The type of data in the DKIM record." + }, + "data": { + "type": "string", + "description": "The DKIM record." + }, + "valid": { + "type": "boolean", + "description": "Indicates if the DKIM record is valid." + } + } + } + } } - } + }, + "required": [ + "id", + "domain", + "subdomain", + "username", + "user_id", + "ips", + "custom_spf", + "default", + "legacy", + "automatic_security", + "valid", + "dns" + ] } - - contactdb_list: |- + - transactional_template: |- { - "title": "ContactDB lists", "type": "object", "properties": { "id": { - "type": "integer", - "description": "The reference ID of your list." + "type": "string", + "description": "The ID of the transactional template." }, "name": { "type": "string", - "description": "The name of your list." + "description": "The name for the transactional template.", + "maxLength": 100 }, - "recipient_count": { - "type": "integer", - "description": "The count of recipients currently in the list." + "versions": { + "type": "array", + "description": "The different versions of this transactional template.", + "items": { + "$ref": "#/definitions/transactional_template_version" + } } }, "required": [ "id", - "name", - "recipient_count" + "name" ] } - - user_profile: |- + - suppression_group: |- { "type": "object", "properties": { - "address": { - "type": "string" - }, - "address2": { - "type": "string" - }, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" + "id": { + "type": "number", + "description": "The id of the suppression group." }, - "phone": { - "type": "string" + "name": { + "type": "string", + "description": "The name of the suppression group. Each group created by a user must have a unique name.", + "maxLength": 30 }, - "state": { - "type": "string" + "description": { + "type": "string", + "description": "A description of the suppression group.", + "maxLength": 100 }, - "website": { - "type": "string" + "last_email_sent_at": { + "type": "null" }, - "zip": { - "type": "string" + "is_default": { + "type": "boolean", + "default": "false", + "description": "Indicates if this is the default suppression group." } - } + }, + "required": [ + "id", + "name", + "description" + ] } - - monitor: |- + - advanced_stats_country: |- { - "title": "Create monitor settings request", "type": "object", "properties": { - "email": { + "date": { "type": "string", - "description": "The email address to send emails at the frequency specified for monitoring.", - "format": "email" + "description": "The date that the events occurred." }, - "frequency": { - "type": "number", - "description": "The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. " + "stats": { + "type": "array", + "description": "The statistics of the email events.", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of segmentation." + }, + "name": { + "type": "string", + "description": "The name of the specific segmentation." + }, + "metrics": { + "type": "object", + "description": "The individual events and their stats.", + "required": [ + "clicks", + "opens", + "unique_clicks", + "unique_opens" + ], + "properties": { + "clicks": { + "type": "integer", + "description": "The number of links that were clicked in your emails." + }, + "opens": { + "type": "integer", + "description": "The total number of times your emails were opened by recipients." + }, + "unique_clicks": { + "type": "integer", + "description": "The number of unique recipients who clicked links in your emails." + }, + "unique_opens": { + "type": "integer", + "description": "The number of unique recipients who opened your emails." + } + } + } + }, + "required": [ + "type", + "name", + "metrics" + ] + } } }, "required": [ - "email", - "frequency" + "date", + "stats" ] } - - api_key_name_id: |- + - advanced_stats_opens: |- { "type": "object", "properties": { - "api_key_id": { - "type": "string", - "description": "The ID of your API Key. " - }, - "name": { + "date": { "type": "string", - "description": "The name of your API Key." - } - } - } - - mail_settings_forward_bounce: |- - { - "type": "object", - "properties": { - "email": { - "type": [ - "string", - "null" - ] + "description": "The date that the events occurred." }, - "enabled": { - "type": "boolean" - } - } - } - - 'global:ErrorResponse': |- - { - "type": "object", - "properties": { - "errors": { + "stats": { "type": "array", + "description": "The statistics of the email events.", "items": { "type": "object", "properties": { - "field": { - "type": [ - "string", - "null" - ], - "description": "The field that generated the error." + "type": { + "type": "string", + "description": "The type of segmentation." }, - "message": { + "name": { "type": "string", - "description": "The error message." + "description": "The name of the specific segmentation." + }, + "metrics": { + "type": "object", + "description": "The individual events and their stats.", + "required": [ + "opens", + "unique_opens" + ], + "properties": { + "opens": { + "type": "integer", + "description": "The total number of times your emails were opened by recipients." + }, + "unique_opens": { + "type": "integer", + "description": "The number of unique recipients who opened your emails." + } + } } }, "required": [ - "message" + "type", + "name", + "metrics" ] } } - } + }, + "required": [ + "date", + "stats" + ] } - - suppression_bounce: |- + - advanced_stats_clicks: |- { "type": "object", "properties": { - "created": { - "type": "number", - "description": "The unix timestamp for when the bounce record was created at SendGrid." - }, - "email": { - "type": "string" - }, - "reason": { + "date": { "type": "string", - "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." + "description": "The date that the events occurred." }, - "status": { - "type": "string", - "description": "Enhanced SMTP bounce response" - } - } - } - - contactdb_recipient: |- - { - "type": "object", - "properties": { - "recipients": { + "stats": { "type": "array", + "description": "The statistics of the email events.", "items": { "type": "object", "properties": { - "id": { + "type": { "type": "string", - "description": "The ID of this recipient." - }, - "created_at": { - "type": "number", - "description": "The time this record was created in your contactdb, in unixtime." - }, - "custom_fields": { - "type": "array", - "description": "The custom fields assigned to this recipient and their values.", - "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id_value" - } + "description": "The type of segmentation." }, - "email": { + "name": { "type": "string", - "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", - "format": "email" - }, - "first_name": { - "type": [ - "string", - "null" - ], - "description": "The first name of this recipient. This is a default custom field that SendGrid provides." - }, - "last_name": { - "type": [ - "string", - "null" - ], - "description": "The last name of the recipient." + "description": "The name of the specific segmentation." }, - "last_clicked": { - "type": [ - "number", - "null" + "metrics": { + "type": "object", + "description": "The individual events and their stats.", + "required": [ + "clicks", + "unique_clicks" ], - "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime." + "properties": { + "clicks": { + "type": "integer", + "description": "The number of links that were clicked in your emails." + }, + "unique_clicks": { + "type": "integer", + "description": "The number of unique recipients who clicked links in your emails." + } + } + } + }, + "required": [ + "type", + "name", + "metrics" + ] + } + } + }, + "required": [ + "date", + "stats" + ] + } + - advanced_stats_mailbox_provider: |- + { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date that the events occurred." + }, + "stats": { + "type": "array", + "description": "The statistics of the email events.", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of segmentation." }, - "last_emailed": { - "type": [ - "number", - "null" - ], - "description": "The last time this user was emailed by one of your campaigns, in unixtime." + "name": { + "type": "string", + "description": "The name of the specific segmentation." }, - "last_opened": { - "type": [ - "number", - "null" + "metrics": { + "type": "object", + "description": "The individual events and their stats.", + "required": [ + "clicks", + "opens", + "unique_clicks", + "unique_opens", + "blocks", + "bounces", + "deferred", + "delivered", + "drops", + "spam_reports" ], - "description": "The last time this recipient opened an email from you, in unixtime." - }, - "updated_at": { - "type": "number", - "description": "The last update date for this recipient's record." + "properties": { + "clicks": { + "type": "integer", + "description": "The number of links that were clicked in your emails." + }, + "opens": { + "type": "integer", + "description": "The total number of times your emails were opened by recipients." + }, + "unique_clicks": { + "type": "integer", + "description": "The number of unique recipients who clicked links in your emails." + }, + "unique_opens": { + "type": "integer", + "description": "The number of unique recipients who opened your emails." + }, + "blocks": { + "type": "integer", + "description": "The number of emails that were not allowed to be delivered by ISPs." + }, + "bounces": { + "type": "integer", + "description": "The number of emails that bounced instead of being delivered." + }, + "deferred": { + "type": "integer", + "description": "The number of emails that temporarily could not be delivered." + }, + "delivered": { + "type": "integer", + "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." + }, + "drops": { + "type": "integer", + "description": "The number of emails that were not delivered due to the recipient email address being on a suppression list." + }, + "spam_reports": { + "type": "integer", + "description": "The number of recipients who marked your email as spam." + } + } } }, "required": [ - "email" + "type", + "name", + "metrics" ] } } + }, + "required": [ + "date", + "stats" + ] + } + - stats: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date that the statistics were gathered." + }, + "stats": { + "type": "array", + "description": "The list of statistics.", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of segmentation." + }, + "name": { + "type": "string", + "description": "The name of the specific segmentation." + }, + "metrics": { + "type": "object", + "description": "The individual events and their statistics.", + "properties": { + "blocks": { + "type": "integer", + "description": "The number of emails that were not allowed to be delivered by ISPs." + }, + "bounce_drops": { + "type": "integer", + "description": "The number of emails that were dropped because of a bounce." + }, + "bounces": { + "type": "integer", + "description": "The number of emails that bounced instead of being delivered." + }, + "clicks": { + "type": "integer", + "description": "The number of links that were clicked in your emails." + }, + "deferred": { + "type": "integer", + "description": "The number of emails that temporarily could not be delivered. " + }, + "delivered": { + "type": "integer", + "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." + }, + "invalid_emails": { + "type": "integer", + "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." + }, + "opens": { + "type": "integer", + "description": "The total number of times your emails were opened by recipients." + }, + "processed": { + "type": "integer", + "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." + }, + "requests": { + "type": "integer", + "description": "The number of emails that were requested to be delivered." + }, + "spam_report_drops": { + "type": "integer", + "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." + }, + "spam_reports": { + "type": "integer", + "description": "The number of recipients who marked your email as spam." + }, + "unique_clicks": { + "type": "integer", + "description": "The number of unique recipients who clicked links in your emails." + }, + "unique_opens": { + "type": "integer", + "description": "The number of unique recipients who opened your emails." + }, + "unsubscribe_drops": { + "type": "integer", + "description": "The number of emails dropped due to a recipient unsubscribing from your emails." + }, + "unsubscribes": { + "type": "integer", + "description": "The number of recipients who unsubscribed from your emails." + } + } + } + } + } + } + } } } - - 'whitelabel::domain': |- + - link_whitelabel: |- { "type": "object", "properties": { "id": { - "type": "number", - "description": "The ID of the domain whitelabel." - }, - "user_id": { - "type": "number", - "description": "The ID of the user that this whitelabel will be associated with." + "type": "integer", + "description": "The id of the link whitelabel." }, - "subdomain": { + "domain": { "type": "string", - "description": "The subdomain to use for this domain whitelabel." + "description": "The root domain for this link whitelabel." }, - "domain": { + "subdomain": { "type": "string", - "description": "The domain that this whitelabel is being created for." + "description": "The subdomain used to generate the DNS records for this link whitelabel. This subdomain must be different from the subdomain used for your domain whitelabel." }, "username": { "type": "string", - "description": "The username that this whitelabel will be associated with." - }, - "ips": { - "type": "array", - "description": "The IPs to be included in the custom SPF record for this domain whitelabel.", - "items": { - "type": "object", - "properties": {} - } + "description": "The username of the account that this link whitelabel is associated with." }, - "custom_spf": { - "type": "boolean", - "description": "Indicates whether this domain whitelabel will use custom SPF." + "user_id": { + "type": "integer", + "description": "The id of the user that this whitelabel is associated with." }, "default": { "type": "boolean", - "description": "Indicates if this domain whitelabel is the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this domain whitelabel was created using the legacy whitelabel tool." + "description": "Indicates if this is the default link whitelabel.", + "enum": [ + true, + false + ] }, - "automatic_security": { + "valid": { "type": "boolean", - "description": "Indicates if this domain whitelabel uses automated security." + "description": "Indicates if this link whitelabel is valid.", + "enum": [ + true, + false + ] }, - "valid": { + "legacy": { "type": "boolean", - "description": "Indicates if this is a valid whitelabel." + "description": "Indicates if this link whitelabel was created using the legacy whitelabel tool.", + "enum": [ + true, + false + ] }, "dns": { "type": "object", - "description": "The DNS records for this whitelabel that are used to authenticate the sending domain.", + "description": "The DNS records generated for this link whitelabel.", "required": [ - "mail_cname", - "dkim1", - "dkim2" + "domain_cname" ], "properties": { - "mail_cname": { + "domain_cname": { "type": "object", - "description": "The CNAME for your sending domain that points to sendgrid.net.", + "description": "The DNS record generated to point to your link whitelabel subdomain.", "required": [ "valid", "type", @@ -16512,283 +16082,416 @@ schemas: "properties": { "valid": { "type": "boolean", - "description": "Indicates if this is a valid CNAME." + "description": "Indicates if the DNS record is valid.", + "enum": [ + true, + false + ] }, "type": { "type": "string", - "description": "The type of DNS record." + "description": "The type of DNS record that was generate.", + "enum": [ + "cname", + "txt", + "mx" + ] }, "host": { "type": "string", - "description": "The domain that this CNAME is created for.", + "description": "The domain that this whitelabel will use when whitelabeling the links in your email.", "format": "hostname" }, "data": { "type": "string", - "description": "The CNAME record." + "description": "The domain that the DNS record points to.", + "format": "hostname" } } }, - "dkim1": { + "owner_cname": { "type": "object", - "description": "A DNS record.", - "required": [ - "valid", - "type", - "host", - "data" - ], + "description": "The DNS record generated to verify who created the link whitelabel.", "properties": { "valid": { "type": "boolean", - "description": "Indicates if this is a valid DNS record." + "description": "Indicates if the DNS record is valid.", + "enum": [ + true, + false + ] }, "type": { "type": "string", - "description": "The type of DNS record." + "description": "The type of DNS record generated.", + "enum": [ + "cname", + "txt", + "mx" + ] }, "host": { "type": "string", - "description": "The domain that this DNS record was created for." + "description": "Used to verify the link whitelabel. The subdomain of this domain is the user id of the user who created the link whitelabel.", + "format": "hostname" }, "data": { "type": "string", - "description": "The DNS record." + "description": "The domain that the DNS record points to.", + "format": "hostname" } - } - }, - "dkim2": { - "type": "object", - "description": "A DNS record.", + }, "required": [ "valid", - "type", "host", "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this DNS record was created for." - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } + ] } } } }, "required": [ "id", - "user_id", - "subdomain", "domain", + "subdomain", "username", - "ips", - "custom_spf", + "user_id", "default", - "legacy", - "automatic_security", "valid", + "legacy", "dns" ] } - - 'whitelabel:domain_spf': |- + - ip_warmup_response: |- + { + "type": "array", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string" + }, + "start_date": { + "type": "integer" + } + } + } + } + - ip_pool: |- + { + "type": "object", + "properties": { + "name": { + "type": "string" + } + } + } + - category_stats: |- + { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date the statistics were gathered." + }, + "stats": { + "type": "array", + "items": { + "type": "object", + "properties": { + "metrics": { + "type": "object", + "properties": { + "blocks": { + "type": "integer", + "description": "The number of emails that were not allowed to be delivered by ISPs." + }, + "bounce_drops": { + "type": "integer", + "description": "The number of emails that were dropped because of a bounce." + }, + "bounces": { + "type": "integer", + "description": "The number of emails that bounced instead of being delivered." + }, + "clicks": { + "type": "integer", + "description": "The number of links that were clicked." + }, + "deferred": { + "type": "integer", + "description": "The number of emails that temporarily could not be delivered." + }, + "delivered": { + "type": "integer", + "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." + }, + "invalid_emails": { + "type": "integer", + "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." + }, + "opens": { + "type": "integer", + "description": "The total number of times your emails were opened by recipients." + }, + "processed": { + "type": "integer", + "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." + }, + "requests": { + "type": "integer", + "description": "The number of emails that were requested to be delivered." + }, + "spam_report_drops": { + "type": "integer", + "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." + }, + "spam_reports": { + "type": "integer", + "description": "The number of recipients who marked your email as spam." + }, + "unique_clicks": { + "type": "integer", + "description": "The number of unique recipients who clicked links in your emails." + }, + "unique_opens": { + "type": "integer", + "description": "The number of unique recipients who opened your emails." + }, + "unsubscribe_drops": { + "type": "integer", + "description": "The number of emails dropped due to a recipient unsubscribing from your emails." + }, + "unsubscribes": { + "type": "integer", + "description": "The number of recipients who unsubscribed from your emails." + } + }, + "required": [ + "blocks", + "bounce_drops", + "bounces", + "clicks", + "deferred", + "delivered", + "invalid_emails", + "opens", + "processed", + "requests", + "spam_report_drops", + "spam_reports", + "unique_clicks", + "unique_opens", + "unsubscribe_drops", + "unsubscribes" + ] + }, + "name": { + "type": "string", + "description": "The name of the category." + }, + "type": { + "type": "string", + "description": "How you are segmenting your statistics." + } + }, + "required": [ + "type" + ] + } + } + }, + "required": [ + "date" + ] + } + - ip_whitelabel: |- { "type": "object", "properties": { "id": { "type": "integer", - "description": "The ID of the domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel was created for." + "description": "The id of the IP whitelabel." }, - "subdomain": { + "ip": { "type": "string", - "description": "The subdomain that was used to create this whitelabel." + "description": "The IP address that this whitelabel was created for." }, - "username": { + "rdns": { "type": "string", - "description": "The username of the account that this whitelabel is associated with." - }, - "user_id": { - "type": "integer", - "description": "The user_id of the account that this whitelabel is associated with." + "description": "The reverse DNS record for the IP address. This points to the IP whitelabel subdomain." }, - "ips": { + "users": { "type": "array", - "description": "The IP addresses that are included in the SPF record for this whitelabel.", - "items": {} + "description": "The users who are able to send mail from the IP.", + "items": { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The username of the user who can send mail from this IP." + }, + "user_id": { + "type": "integer", + "description": "The ID of the user who can send mail from this IP." + } + }, + "required": [ + "username", + "user_id" + ] + } }, - "custom_spf": { - "type": "boolean", - "description": "Indicates if this whitelabel uses custom SPF." + "subdomain": { + "type": "string", + "description": "The subdomain created for this IP whitelabel. This is where the rDNS record points." }, - "default": { + "domain": { + "type": "string", + "description": "The root, or sending, domain." + }, + "valid": { "type": "boolean", - "description": "Indicates if this is the default whitelabel." + "description": "Indicates if this is a valid whitelabel." }, "legacy": { "type": "boolean", "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "dns": { + "a_record": { "type": "object", - "description": "The DNS records for this whitelabel.", "required": [ - "mail_server", - "subdomain_spf", - "domain_spf", - "dkim" + "valid", + "type", + "host", + "data" ], "properties": { - "mail_server": { - "type": "object", - "description": "Designates which mail server is responsible for accepting messages from a domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain sending the messages." - }, - "type": { - "type": "string", - "description": "They type of DNS record." - }, - "data": { - "type": "string", - "description": "The mail server responsible for accepting messages from the sending domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - } - } + "valid": { + "type": "boolean", + "description": "Indicates if the a_record is valid." }, - "subdomain_spf": { - "type": "object", - "description": "The SPF record for the subdomain used to create this whitelabel.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid SPF record." - } - } + "type": { + "type": "string", + "description": "The type of DNS record." }, - "domain_spf": { - "type": "object", - "description": "The SPF record for the root domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The root domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - } - } + "host": { + "type": "string", + "description": "This is the web address that will be mapped to the IP address." }, - "dkim": { - "type": "object", - "description": "The DKIM record for messages sent using this whitelabel.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The DNS labels for the DKIM signature." - }, - "type": { - "type": "string", - "description": "The type of data in the DKIM record." - }, - "data": { - "type": "string", - "description": "The DKIM record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the DKIM record is valid." - } - } + "data": { + "type": "string", + "description": "The IP address being whitelabeled." } } } }, "required": [ "id", - "domain", + "ip", + "rdns", + "users", "subdomain", - "username", - "user_id", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", + "domain", "valid", - "dns" + "legacy", + "a_record" + ] + } + - google_analytics_settings: "{\n \"type\": \"object\",\n \"properties\": {\n \"enabled\": {\n \"type\": \"boolean\",\n \"description\": \"Indicates if Google Analytics is enabled.\"\n },\n \"utm_campaign\": {\n \"type\": \"string\",\n \"description\": \"The name of the campaign.\"\n },\n \"utm_content\": {\n \"type\": \"string\",\n \"description\": \"Used to differentiate ads\"\n },\n \"utm_medium\": {\n \"type\": \"string\",\n \"description\": \"Name of the marketing medium (e.g. \\\"Email\\\").\"\n },\n \"utm_source\": {\n \"type\": \"string\",\n \"description\": \"Name of the referrer source. \"\n },\n \"utm_term\": {\n \"type\": \"string\",\n \"description\": \"Any paid keywords.\"\n }\n }\n}" + - subscription_tracking_settings: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if subscription tracking is enabled." + }, + "html_content": { + "type": "string", + "description": "The information and HTML for your unsubscribe link. " + }, + "landing": { + "type": "string", + "description": "The HTML that will be displayed on the page that your customers will see after clicking unsubscribe, hosted on SendGrid’s server." + }, + "plain_content": { + "type": "string", + "description": "The information in plain text for your unsubscribe link. You should have the “<% %>” tag in your content, otherwise the user will have no URL for unsubscribing." + }, + "replace": { + "type": "string", + "description": "Your custom defined replacement tag for your templates. Use this tag to place your unsubscribe content anywhere in your emailtemplate." + }, + "url": { + "type": "string", + "description": "The URL where you would like your users sent to unsubscribe." + } + } + } + - mail_settings_footer: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the Footer mail setting is currently enabled." + }, + "html_content": { + "type": "string", + "description": "The custom HTML content of your email footer." + }, + "plain_content": { + "type": "string", + "description": "The plain text content of your email footer." + } + } + } + - mail_settings_spam_check: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if your Spam Checker mail setting is enabled." + }, + "max_score": { + "type": "integer", + "default": 5, + "description": "The spam threshold. Can range from 1 to 10. The lower the number, the more strict the filtering.", + "minimum": 1, + "maximum": 10 + }, + "url": { + "type": "string", + "description": "The inbound parse URL where you would like the spam messages to be sent to." + } + }, + "required": [ + "enabled" ] } + - mail_settings_bounce_purge: |- + { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the bounce purge mail setting is enabled." + }, + "soft_bounces": { + "type": [ + "integer", + "null" + ], + "description": "The number of days, after which SendGrid will purge all contacts from your soft bounces suppression lists." + }, + "hard_bounces": { + "type": [ + "integer", + "null" + ], + "description": "The number of days, after which SendGrid will purge all contacts from your hard bounces suppression lists." + } + } + } diff --git a/swagger-stoplight.json b/swagger.json similarity index 96% rename from swagger-stoplight.json rename to swagger.json index 58e144b..d530271 100644 --- a/swagger-stoplight.json +++ b/swagger.json @@ -927,6 +927,35 @@ "global:id": { "type": "integer" }, + "google_analytics_settings": { + "properties": { + "enabled": { + "description": "Indicates if Google Analytics is enabled.", + "type": "boolean" + }, + "utm_campaign": { + "description": "The name of the campaign.", + "type": "string" + }, + "utm_content": { + "description": "Used to differentiate ads", + "type": "string" + }, + "utm_medium": { + "description": "Name of the marketing medium (e.g. \"Email\").", + "type": "string" + }, + "utm_source": { + "description": "Name of the referrer source. ", + "type": "string" + }, + "utm_term": { + "description": "Any paid keywords.", + "type": "string" + } + }, + "type": "object" + }, "ip_pool": { "properties": { "name": { @@ -1199,23 +1228,14 @@ ], "type": "object" }, - "mail_settings::patch": { - "properties": { - "email": { - "type": "string" - }, - "enabled": { - "type": "boolean" - } - }, - "type": "object" - }, "mail_settings_address_whitelabel": { "properties": { "enabled": { + "description": "Indicates if you have an email address whitelist enabled. ", "type": "boolean" }, "list": { + "description": "All email address that are currently on the whitelist.", "items": { "type": "string" }, @@ -1227,9 +1247,11 @@ "mail_settings_bcc": { "properties": { "email": { + "description": "The email address that will be sent a blind carbon copy.", "type": "string" }, "enabled": { + "description": "Indicates if the BCC setting is enabled.", "type": "boolean" } }, @@ -1238,15 +1260,18 @@ "mail_settings_bounce_purge": { "properties": { "enabled": { + "description": "Indicates if the bounce purge mail setting is enabled.", "type": "boolean" }, "hard_bounces": { + "description": "The number of days, after which SendGrid will purge all contacts from your hard bounces suppression lists.", "type": [ "integer", "null" ] }, "soft_bounces": { + "description": "The number of days, after which SendGrid will purge all contacts from your soft bounces suppression lists.", "type": [ "integer", "null" @@ -1258,12 +1283,15 @@ "mail_settings_footer": { "properties": { "enabled": { + "description": "Indicates if the Footer mail setting is currently enabled.", "type": "boolean" }, "html_content": { + "description": "The custom HTML content of your email footer.", "type": "string" }, "plain_content": { + "description": "The plain text content of your email footer.", "type": "string" } }, @@ -1272,12 +1300,14 @@ "mail_settings_forward_bounce": { "properties": { "email": { + "description": "The email address that you would like your bounce reports forwarded to.", "type": [ "string", "null" ] }, "enabled": { + "description": "Indicates if the bounce forwarding mail setting is enabled.", "type": "boolean" } }, @@ -1286,12 +1316,24 @@ "mail_settings_forward_spam": { "properties": { "email": { - "type": [ - "string", - "null" - ] + "description": "The email address where you would like the spam reports to be forwarded.", + "type": "string" }, "enabled": { + "description": "Indicates if the Forward Spam setting is enabled.", + "type": "boolean" + } + }, + "type": "object" + }, + "mail_settings_patch": { + "properties": { + "email": { + "description": "The email address of the recipient.", + "type": "string" + }, + "enabled": { + "description": "Indicates if the mail setting is enabled.", "type": "boolean" } }, @@ -1300,23 +1342,34 @@ "mail_settings_spam_check": { "properties": { "enabled": { + "description": "Indicates if your Spam Checker mail setting is enabled.", "type": "boolean" }, "max_score": { + "default": 5, + "description": "The spam threshold. Can range from 1 to 10. The lower the number, the more strict the filtering.", + "maximum": 10, + "minimum": 1, "type": "integer" }, "url": { + "description": "The inbound parse URL where you would like the spam messages to be sent to.", "type": "string" } }, + "required": [ + "enabled" + ], "type": "object" }, "mail_settings_template": { "properties": { "enabled": { + "description": "Indicates if the legacy email template setting is enabled.", "type": "boolean" }, "html_content": { + "description": "The HTML content that you want to use for your legacy email template.", "type": "string" } }, @@ -1461,6 +1514,35 @@ }, "type": "array" }, + "subscription_tracking_settings": { + "properties": { + "enabled": { + "description": "Indicates if subscription tracking is enabled.", + "type": "boolean" + }, + "html_content": { + "description": "The information and HTML for your unsubscribe link. ", + "type": "string" + }, + "landing": { + "description": "The HTML that will be displayed on the page that your customers will see after clicking unsubscribe, hosted on SendGrid\u2019s server.", + "type": "string" + }, + "plain_content": { + "description": "The information in plain text for your unsubscribe link. You should have the \u201c<% %>\u201d tag in your content, otherwise the user will have no URL for unsubscribing.", + "type": "string" + }, + "replace": { + "description": "Your custom defined replacement tag for your templates. Use this tag to place your unsubscribe content anywhere in your emailtemplate.", + "type": "string" + }, + "url": { + "description": "The URL where you would like your users sent to unsubscribe.", + "type": "string" + } + }, + "type": "object" + }, "subuser": { "properties": { "disabled": { @@ -9756,15 +9838,17 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get all mail settings", + "description": "**This endpoint allows you to retrieve a list of all mail settings.**\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve all mail settings", "parameters": [ { + "description": "The number of settings to return.", "in": "query", "name": "limit", "type": "integer" }, { + "description": "Where in the list of results to begin displaying settings.", "in": "query", "name": "offset", "type": "integer" @@ -9845,26 +9929,40 @@ "schema": { "properties": { "result": { + "description": "The list of all mail settings.", "items": { "properties": { "description": { + "description": "A description of the mail setting.", "type": "string" }, "enabled": { + "description": "Indicates if this mail setting is currently enabled.", "type": "boolean" }, "name": { + "description": "The name of the mail setting.", "type": "string" }, "title": { + "description": "The title of the mail setting.", "type": "string" } }, + "required": [ + "title", + "enabled", + "name", + "description" + ], "type": "object" }, "type": "array" } }, + "required": [ + "result" + ], "type": "object" } } @@ -9883,8 +9981,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get address whitelist mail settings", + "description": "**This endpoint allows you to retrieve your current email address whitelist settings.**\n\nThe address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain \u201cexample.com,\u201d and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve address whitelist mail settings", "parameters": [], "produces": [ "application/json" @@ -9917,7 +10015,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current email address whitelist settings.**\n\nThe address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain \u201cexample.com,\u201d and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update address whitelist mail settings", "parameters": [ { @@ -9926,9 +10024,11 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if your email address whitelist is enabled.", "type": "boolean" }, "list": { + "description": "Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.", "items": { "type": "string" }, @@ -9971,8 +10071,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get BCC mail settings", + "description": "**This endpoint allows you to retrieve your current BCC mail settings.**\n\nWhen the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve all BCC mail settings", "parameters": [], "produces": [ "application/json" @@ -10003,14 +10103,14 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current BCC mail settings.**\n\nWhen the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update BCC mail settings", "parameters": [ { "in": "body", "name": "body", "schema": { - "$ref": "#/definitions/mail_settings::patch" + "$ref": "#/definitions/mail_settings_patch" } } ], @@ -10027,7 +10127,7 @@ } }, "schema": { - "$ref": "#/definitions/mail_settings::patch" + "$ref": "#/definitions/mail_settings_patch" } } }, @@ -10044,8 +10144,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get bounce purge mail settings", + "description": "**This endpoint allows you to retrieve your current bounce purge settings.**\n\nThis setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve bounce purge mail settings", "parameters": [], "produces": [ "application/json" @@ -10077,25 +10177,14 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current bounce purge settings.**\n\nThis setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update bounce purge mail settings", "parameters": [ { "in": "body", "name": "body", "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "hard_bounces": { - "type": "integer" - }, - "soft_bounces": { - "type": "integer" - } - }, - "type": "object" + "$ref": "#/definitions/mail_settings_bounce_purge" } } ], @@ -10130,8 +10219,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get footer mail settings [params can be null?]", + "description": "**This endpoint allows you to retrieve your current Footer mail settings.**\n\nThe footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve footer mail settings", "parameters": [], "produces": [ "application/json" @@ -10163,7 +10252,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current Footer mail settings.**\n\nThe footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update footer mail settings", "parameters": [ { @@ -10205,8 +10294,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get forward bounce mail settings", + "description": "**This endpoint allows you to retrieve your current bounce forwarding mail settings.**\n\nActivating this setting allows you to specify an email address to which bounce reports are forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve forward bounce mail settings", "parameters": [], "produces": [ "application/json" @@ -10237,22 +10326,14 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current bounce forwarding mail settings.**\n\nActivating this setting allows you to specify an email address to which bounce reports are forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update forward bounce mail settings", "parameters": [ { "in": "body", "name": "body", "schema": { - "properties": { - "email": { - "type": "string" - }, - "enabled": { - "type": "boolean" - } - }, - "type": "object" + "$ref": "#/definitions/mail_settings_forward_bounce" } } ], @@ -10286,8 +10367,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get forward spam mail settings", + "description": "**This endpoint allows you to retrieve your current Forward Spam mail settings.**\n\nEnabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve forward spam mail settings", "parameters": [], "produces": [ "application/json" @@ -10318,7 +10399,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current Forward Spam mail settings.**\n\nEnabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update forward spam mail settings", "parameters": [ { @@ -10359,8 +10440,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get plain content mail settings", + "description": "**This endpoint allows you to retrieve your current Plain Content mail settings.**\n\nThe plain content setting will automatically convert any plain text emails that you send to HTML before sending.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve plain content mail settings", "parameters": [], "produces": [ "application/json" @@ -10376,6 +10457,7 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if the Plain Content mail setting is enabled.", "type": "boolean" } }, @@ -10395,7 +10477,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current Plain Content mail settings.**\n\nThe plain content setting will automatically convert any plain text emails that you send to HTML before sending.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update plain content mail settings", "parameters": [ { @@ -10404,6 +10486,7 @@ "schema": { "properties": { "enabled": { + "description": "The new setting you would like to use for your Plain Content mail setting.", "type": "boolean" } }, @@ -10425,6 +10508,7 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if your Plain Content mail setting is enabled.", "type": "boolean" } }, @@ -10445,8 +10529,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get spam check mail settings", + "description": "**This endpoint allows you to retrieve your current Spam Checker mail settings.**\n\nThe spam checker filter notifies you when emails are detected that exceed a predefined spam threshold.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve spam check mail settings", "parameters": [], "produces": [ "application/json" @@ -10478,7 +10562,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current spam checker mail settings.**\n\nThe spam checker filter notifies you when emails are detected that exceed a predefined spam threshold.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update spam check mail settings", "parameters": [ { @@ -10487,12 +10571,18 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if you want the spam check mail setting to be enabled or not.", "type": "boolean" }, "max_score": { + "default": 5, + "description": "The new max score, or spam threshold that you would like to set for the spam checker.", + "maximum": 10, + "minimum": 1, "type": "integer" }, "url": { + "description": "The Inbound Parse URL where you would like your spam reports to be sent to.", "type": "string" } }, @@ -10531,8 +10621,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get template mail settings", + "description": "**This endpoint allows you to retrieve your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", + "operationId": "Retrieve legacy template mail settings", "parameters": [], "produces": [ "application/json" @@ -10547,15 +10637,7 @@ } }, "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/mail_settings_template" } } }, @@ -10571,7 +10653,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid\u2019s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html).", "operationId": "Update template mail settings", "parameters": [ { @@ -10580,9 +10662,11 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if you want to enable the legacy email template mail setting.", "type": "boolean" }, "html_content": { + "description": "The new HTML content for your legacy email template.", "type": "string" } }, @@ -14010,15 +14094,17 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get Tracking Settings", + "description": "**This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.**\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", + "operationId": "Retrieve Tracking Settings", "parameters": [ { + "description": "The number of settings to return.", "in": "query", "name": "limit", "type": "integer" }, { + "description": "Where in the list of results you want to begin retrieving settings.", "in": "query", "name": "offset", "type": "integer" @@ -14045,18 +14131,23 @@ "schema": { "properties": { "result": { + "description": "The list of all tracking settings.", "items": { "properties": { "description": { + "description": "A description about the event that is being tracked.", "type": "string" }, "enabled": { + "description": "Indicates if this tracking setting is currently enabled.", "type": "boolean" }, "name": { + "description": "The name of the event being tracked.", "type": "string" }, "title": { + "description": "The title of the tracking setting.", "type": "string" } }, @@ -14083,8 +14174,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get Click Track Settings", + "description": "**This endpoint allows you to retrieve your current click tracking setting.**\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", + "operationId": "Retrieve Click Track Settings", "parameters": [], "produces": [ "application/json" @@ -14101,12 +14192,18 @@ "schema": { "properties": { "enable_text": { + "description": "Indicates if click tracking is enabled for plain text emails.", "type": "boolean" }, "enabled": { + "description": "Indicates if click tracking is enabled or disabled.", "type": "boolean" } }, + "required": [ + "enable_text", + "enabled" + ], "type": "object" } } @@ -14123,7 +14220,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.**\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "Update Click Tracking Settings", "parameters": [ { @@ -14132,6 +14229,7 @@ "schema": { "properties": { "enabled": { + "description": "The setting you want to use for click tracking.", "type": "boolean" } }, @@ -14154,12 +14252,18 @@ "schema": { "properties": { "enable_text": { + "description": "Indicates if click tracking is enabled for plain text emails", "type": "boolean" }, "enabled": { + "description": "The new setting new setting for click tracking.", "type": "boolean" } }, + "required": [ + "enable_text", + "enabled" + ], "type": "object" } } @@ -14177,8 +14281,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get Google Analytics Settings", + "description": "**This endpoint allows you to retrieve your current setting for Google Analytics.**\n\nFor more information about using Google Analytics, please refer to [Google\u2019s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on [\"Best Practices for Campaign Building\"](https://support.google.com/analytics/answer/1037445).\n\nWe default the settings to Google\u2019s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html).\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", + "operationId": "Retrieve Google Analytics Settings", "parameters": [], "produces": [ "application/json" @@ -14197,27 +14301,7 @@ } }, "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/google_analytics_settings" } } }, @@ -14233,34 +14317,14 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current setting for Google Analytics.**\n\nFor more information about using Google Analytics, please refer to [Google\u2019s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on [\"Best Practices for Campaign Building\"](https://support.google.com/analytics/answer/1037445).\n\nWe default the settings to Google\u2019s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html).\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "Update Google Analytics Settings", "parameters": [ { "in": "body", "name": "body", "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/google_analytics_settings" } } ], @@ -14281,27 +14345,7 @@ } }, "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/google_analytics_settings" } } }, @@ -14318,7 +14362,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to retrieve your current settings for open tracking.**\n\nOpen Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid\u2019s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "Get Open Tracking Settings", "parameters": [], "produces": [ @@ -14335,9 +14379,13 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if open tracking is enabled.", "type": "boolean" } }, + "required": [ + "enabled" + ], "type": "object" } } @@ -14354,7 +14402,7 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current settings for open tracking.**\n\nOpen Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid\u2019s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "Update Open Tracking Settings", "parameters": [ { @@ -14363,6 +14411,7 @@ "schema": { "properties": { "enabled": { + "description": "The new status that you want to set for open tracking.", "type": "boolean" } }, @@ -14384,9 +14433,13 @@ "schema": { "properties": { "enabled": { + "description": "Indicates if open tracking is enabled.", "type": "boolean" } }, + "required": [ + "enabled" + ], "type": "object" } } @@ -14404,8 +14457,8 @@ "consumes": [ "application/json" ], - "description": "", - "operationId": "Get Subscription Tracking Settings", + "description": "**This endpoint allows you to retrieve your current settings for subscription tracking.**\n\nSubscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", + "operationId": "Retrieve Subscription Tracking Settings", "parameters": [], "produces": [ "application/json" @@ -14424,27 +14477,7 @@ } }, "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "url": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/subscription_tracking_settings" } } }, @@ -14460,34 +14493,14 @@ "consumes": [ "application/json" ], - "description": "", + "description": "**This endpoint allows you to update your current settings for subscription tracking.**\n\nSubscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.\n\nYou can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails.\n\nFor more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html).", "operationId": "Update Subscription Tracking Settings", "parameters": [ { "in": "body", "name": "body", "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "url": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/subscription_tracking_settings" } } ], @@ -14508,27 +14521,7 @@ } }, "schema": { - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "url": { - "type": "string" - } - }, - "type": "object" + "$ref": "#/definitions/subscription_tracking_settings" } } }, diff --git a/swagger.yaml b/swagger.yaml index ae3ce83..3aafc51 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -1,1214 +1,1213 @@ swagger: '2.0' +schemes: + - http + - https +basePath: /v3 +host: api.sendgrid.com info: version: '3.0' - title: DX - Web API v3 - Officially Documented Only + title: DX - v3 - Officially Documented Only - DO NOT EDIT 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\n\n" +consumes: + - application/json +produces: + - application/json paths: /partner_settings/sendwithus: parameters: [] - get: + patch: + description: '' + operationId: Update SendWithUs Settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + properties: + body: + description: '' + schema: + type: object + required: + - body responses: '200': description: '' schema: type: object - parameters: [] + summary: '' + get: + description: '' + operationId: Get SendWithUs Settings consumes: - application/json produces: - application/json - operationId: Get SendWithUs Settings + parameters: [] + responses: + '200': + description: '' + schema: + type: object summary: '' - description: '' security: - - {} - patch: + - Authorization: [] + '/asm/groups/{group_id}': + parameters: + - name: group_id + in: path + description: The id of the suppression group you want to delete. + required: true + type: integer + delete: + description: |- + **This endpoint allows you to delete a suppression group.** + + You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list. + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: Delete a suppression group. + consumes: + - application/json + produces: + - application/json + parameters: [] responses: - '200': + '204': description: '' schema: type: object - parameters: - - type: string - name: body - in: formData - required: true + properties: {} + summary: A single suppression group object with all its details + security: + - Authorization: [] + get: + description: |- + **This endpoint allows you to retrieve a single suppression group.** + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: Get information on a single suppression group. + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': description: '' + schema: + type: object + allOf: + - $ref: '#/definitions/suppression_group' + - type: object + properties: + unsubscribes: + type: integer + description: The unsubscribes associated with this group. + examples: + application/json: + id: 100 + name: Newsletters + description: Our monthly newsletter. + last_email_sent_at: null + is_default: true + unsubscribes: 400 + summary: You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the “one-cl + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update or change a suppression group.** + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: Update a suppression group. consumes: - application/json produces: - application/json - operationId: Update SendWithUs Settings + parameters: + - name: body + in: body + schema: + type: object + properties: + id: + type: number + description: The id of the suppression group. + name: + type: string + description: The name of the suppression group. Each group created by a user must have a unique name. + maxLength: 30 + description: + type: string + description: The description of the suppression group. + maxLength: 100 + is_default: + type: boolean + description: Indicates if the suppression group is set as the default group. + required: + - name + responses: + '201': + description: '' + schema: + $ref: '#/definitions/suppression_group' + examples: + application/json: + id: 103 + name: Item Suggestions + description: Suggestions for items our users might like. summary: '' - description: '' - /subusers/stats: + /mailbox_providers/stats: parameters: [] get: + description: |- + **This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.** + + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: Retrieve email statistics by mailbox provider. + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of results to include on each page. + required: false + type: integer + - name: offset + in: query + description: The number of results to exclude. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the stats. Must be either "day", "wee", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: mailbox_providers + in: query + description: The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times. + required: false + type: string responses: '200': description: '' schema: type: array items: - type: object - properties: - date: - type: string - stats: - type: array - items: - properties: - type: - type: string - name: - type: string - metrics: - type: object - properties: - blocks: - type: number - bounce_drops: - type: number - bounces: - type: number - clicks: - type: number - deferred: - type: number - delivered: - type: number - invalid_emails: - type: number - opens: - type: number - processed: - type: number - requests: - type: number - spam_report_drops: - type: number - spam_reports: - type: number - unique_clicks: - type: number - unique_opens: - type: number - unsubscribe_drops: - type: number - unsubscribes: - type: number + $ref: '#/definitions/advanced_stats_mailbox_provider' examples: application/json: - - date: '2015-10-01' + - date: '2015-10-11' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-02' + - date: '2015-10-12' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-03' + - date: '2015-10-13' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-04' + - date: '2015-10-14' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-05' + - date: '2015-10-15' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-06' + - date: '2015-10-16' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-07' + - date: '2015-10-17' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-08' + - date: '2015-10-18' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-09' + - date: '2015-10-19' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-10-10' + - date: '2015-10-20' stats: - - type: subuser - name: Matt_subuser + - type: mailbox_provider + name: Gmail metrics: blocks: 0 - bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - invalid_emails: 0 + drops: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - parameters: - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query - - type: string - name: subusers - in: query - required: true - - type: string - name: start_date - in: query - required: true - - type: string - name: end_date - in: query - consumes: - - application/json - produces: - - application/json - operationId: Subuser Stats provide all of your user’s email statistics for your subuser accounts. - summary: '' - description: '' - security: - - {} - /geo/stats: - parameters: [] - get: - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - date: - type: string + - date: '2015-10-21' stats: - type: array - items: - properties: - type: - type: string - name: - type: string - metrics: - type: object - properties: - clicks: - type: number - opens: - type: number - unique_clicks: - type: number - unique_opens: - type: number - examples: - application/json: - - date: '2015-10-11' + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 1 + drops: 0 + opens: 1 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 1 + - date: '2015-10-22' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-12' + - date: '2015-10-23' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-13' + - date: '2015-10-24' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-14' + - date: '2015-10-25' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-15' + - date: '2015-10-26' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 - opens: 0 + deferred: 0 + delivered: 2 + drops: 0 + opens: 2 + spam_reports: 0 unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-16' + unique_opens: 2 + - date: '2015-10-27' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-17' + - date: '2015-10-28' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-18' + - date: '2015-10-29' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-19' + - date: '2015-10-30' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-20' + - date: '2015-10-31' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-21' + - date: '2015-11-01' stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 1 - unique_clicks: 0 - unique_opens: 1 - - date: '2015-10-22' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-23' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-24' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-25' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-26' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-27' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-28' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-29' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-30' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-31' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-01' - stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-02' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-03' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-04' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-05' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-06' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-07' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-08' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-09' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - date: '2015-11-10' stats: - - type: province - name: TX + - type: mailbox_provider + name: Gmail metrics: + blocks: 0 + bounces: 0 clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 opens: 0 + spam_reports: 0 unique_clicks: 0 unique_opens: 0 - parameters: - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query - - type: string - name: country - in: query - consumes: - - application/json - produces: - - application/json - operationId: Gets email statistics by country and state/province. summary: '' - description: '' - /mail_settings/bounce_purge: - parameters: [] + security: + - Authorization: [] + '/contactdb/lists/{list_id}/recipients': + parameters: + - name: list_id + in: path + required: true + type: string get: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_bounce_purge' - examples: - application/json: - enabled: false - soft_bounces: 1234 - hard_bounces: null - parameters: [] + description: |- + List all the recipients currently on a specific list. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: List Recipients on a List consumes: - application/json produces: - application/json - operationId: Get bounce purge mail settings - summary: '' - description: '' - security: - - {} - patch: + parameters: + - name: page + in: query + description: Page index of first recipient to return (must be a positive integer) + required: false + type: integer + - name: page_size + in: query + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) + required: false + type: integer + - name: list_id + in: query + description: The ID of the list whose recipients you are requesting. + required: true + type: number responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_bounce_purge' + type: object + properties: + recipients: + type: array + items: + $ref: '#/definitions/contactdb_recipient' examples: application/json: - enabled: false - hard_bounces: null - soft_bounces: null - parameters: - - type: string - name: enabled - in: formData - description: '' - - type: string - name: hard_bounces - in: formData - description: '' - - type: string - name: soft_bounces - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Update bounce purge mail settings - summary: '' - description: '' - security: - - {} - /mail_settings/forward_bounce: - parameters: [] - get: - responses: - '200': - description: '' + recipients: + - created_at: 1433348344 + custom_fields: + - id: 6234 + name: age + type: number + value: null + - id: 6233 + name: country + type: text + value: null + - id: 6235 + name: fname + type: text + value: Example + - id: 6239 + name: lname + type: text + value: User + - id: 6240 + name: lname + type: text + value: null + email: example@example.com + first_name: Example + id: ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv== + last_clicked: 1438616117 + last_emailed: 1438613272 + last_name: User + last_opened: 1438616109 + updated_at: 1438616119 + '400': + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" schema: - $ref: '#/definitions/mail_settings_forward_bounce' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - enabled: false - email: null - parameters: [] + errors: + - field: list_id + message: Returned if list_id is not a valid integer + - field: page + message: Returned if page is not a valid integer + - field: page + message: Returned if page is less than 1 + - field: page_size + message: Returned if page_size is not a valid integer + - field: page_size + message: Returned if page_size is less than 1 or greater than 1000 + '404': + description: '"list_id" : "Returned if list_id does not exist"' + schema: + type: object + properties: {} + examples: + application/json: + errors: + - field: list_id + message: Returned if list_id is invalid + summary: '' + security: + - Authorization: [] + post: + description: |- + Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Add Multiple Recipients to a List consumes: - application/json produces: - application/json - operationId: Get forward bounce mail settings - summary: '' - description: '' - security: - - {} - patch: + parameters: + - name: list_id + in: query + description: 'The list to add your recipients to. ' + required: true + type: number responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/mail_settings_forward_bounce' + type: 'null' + '400': + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "" : "Returned if no valid recipient ids were passed" + "" : "Returned if no recipients were added" + "" : "Returned if request body is invalid JSON" + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - email: '' - enabled: true - parameters: - - type: string - name: enabled - in: formData - description: '' - - type: string - name: email - in: formData + errors: + - field: list_id + message: list_id is invalid + - field: recipient_id + message: no valid recipients were provided + - field: null + message: no recipients were added + - field: null + message: request body is invalid JSON + '401': description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"list_id": "Returned if list_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: list_id + message: list_id does not exist + - field: recipient_id + message: recipient_id does not exist + summary: 'Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they ' + security: + - Authorization: [] + '/templates/{template_id}/versions': + parameters: + - name: template_id + in: path + required: true + type: string + post: + description: | + **This endpoint allows you to create a new version of a template.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: Create a new transactional template version. consumes: - application/json produces: - application/json - operationId: Update forward bounce mail settings - summary: '' - description: '' - security: - - {} - /scopes: - parameters: [] - get: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/transactional_template_version' responses: - '200': + '201': description: '' schema: type: object properties: - scopes: - type: array - items: - properties: {} + id: + type: string + description: The id of the new transactional template version. + updated_at: + type: string + description: The date and time that this transactional template version was updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' + required: + - id + - updated_at examples: application/json: - scopes: - - alerts.create - - alerts.read - - alerts.update - - alerts.delete - - asm.groups.create - - asm.groups.read - - asm.groups.update - - asm.groups.delete - - asm.groups.suppressions.create - - asm.groups.suppressions.read - - asm.groups.suppressions.delete - - asm.suppressions.global.create - - asm.suppressions.global.read - - asm.suppressions.global.delete - - billing.create - - billing.read - - billing.update - - billing.delete - - ui.confirm_email - - signup.trigger_confirmation - - ui.provision - - ips.warmup.create - - ips.warmup.read - - ips.warmup.delete - - ips.pools.create - - ips.pools.read - - ips.pools.update - - ips.pools.delete - - ips.pools.ips.create - - ips.pools.ips.delete - - ips.assigned.read - - ips.read - - mail.send - - mail_settings.read - - mail_settings.bcc.read - - mail_settings.bcc.update - - mail_settings.address_whitelist.read - - mail_settings.address_whitelist.update - - mail_settings.footer.read - - mail_settings.footer.update - - mail_settings.forward_spam.read - - mail_settings.forward_spam.update - - mail_settings.plain_content.read - - mail_settings.plain_content.update - - mail_settings.spam_check.read - - mail_settings.spam_check.update - - mail_settings.bounce_purge.read - - mail_settings.bounce_purge.update - - mail_settings.forward_bounce.read - - mail_settings.forward_bounce.update - - partner_settings.read - - partner_settings.new_relic.read - - partner_settings.new_relic.update - - partner_settings.sendwithus.read - - partner_settings.sendwithus.update - - tracking_settings.read - - tracking_settings.click.read - - tracking_settings.click.update - - tracking_settings.subscription.read - - tracking_settings.subscription.update - - tracking_settings.open.read - - tracking_settings.open.update - - tracking_settings.google_analytics.read - - tracking_settings.google_analytics.update - - user.webhooks.event.settings.read - - user.webhooks.event.settings.update - - user.webhooks.event.test.create - - user.webhooks.parse.settings.create - - user.webhooks.parse.settings.read - - user.webhooks.parse.settings.update - - user.webhooks.parse.settings.delete - - stats.read - - stats.global.read - - categories.stats.read - - categories.stats.sums.read - - devices.stats.read - - clients.stats.read - - clients.phone.stats.read - - clients.tablet.stats.read - - clients.webmail.stats.read - - clients.desktop.stats.read - - geo.stats.read - - mailbox_providers.stats.read - - browsers.stats.read - - subusers.stats.read - - subusers.stats.sums.read - - subusers.stats.monthly.read - - user.webhooks.parse.stats.read - - subusers.create - - subusers.read - - subusers.update - - subusers.delete - - subusers.monitor.create - - subusers.monitor.read - - subusers.monitor.update - - subusers.monitor.delete - - subusers.credits.read - - subusers.credits.update - - subusers.credits.remaining.update - - subusers.reputations.read - - subusers.summary.read - - suppression.bounces.read - - suppression.bounces.delete - - suppression.blocks.read - - suppression.blocks.delete - - suppression.invalid_emails.read - - suppression.invalid_emails.delete - - suppression.spam_reports.read - - suppression.spam_reports.delete - - suppression.unsubscribes.create - - suppression.unsubscribes.read - - suppression.unsubscribes.delete - - templates.create - - templates.read - - templates.update - - templates.delete - - templates.versions.create - - templates.versions.read - - templates.versions.update - - templates.versions.delete - - templates.versions.activate.create - - user.account.read - - user.credits.read - - user.email.create - - user.email.read - - user.email.update - - user.email.delete - - user.profile.create - - user.profile.read - - user.profile.update - - user.profile.delete - - user.password.update - - user.timezone.read - - user.timezone.update - - user.username.read - - user.username.update - - user.settings.enforced_tls.read - - user.settings.enforced_tls.update - - api_keys.create - - api_keys.read - - api_keys.update - - api_keys.delete - - email_activity.read - - credentials.create - - credentials.read - - credentials.update - - credentials.delete - - categories.create - - categories.read - - categories.update - - categories.delete - - mail_settings.template.read - - mail_settings.template.update - - user.multifactor_authentication.create - - user.multifactor_authentication.read - - user.multifactor_authentication.update - - user.multifactor_authentication.delete - - admin.impersonate - - newsletter.create - - newsletter.read - - newsletter.update - - newsletter.delete - - marketing_campaigns.create - - marketing_campaigns.read - - marketing_campaigns.update - - marketing_campaigns.delete - - ui.signup_complete - - mail.batch.create - - mail.batch.read - - mail.batch.update - - mail.batch.delete - - user.scheduled_sends.create - - user.scheduled_sends.read - - user.scheduled_sends.update - - user.scheduled_sends.delete - - access_settings.whitelist.create - - access_settings.whitelist.read - - access_settings.whitelist.update - - access_settings.whitelist.delete - parameters: [] + id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 + template_id: ddb96bbc-9b92-425e-8979-99464621b543 + active: 1 + name: example_version_name + html_content: '<%body%>' + plain_content: '<%body%>' + subject: '<%subject%>' + updated_at: '2014-03-19 18:56:33' + summary: '' + security: + - Authorization: [] + /whitelabel/domains/default: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve the default whitelabel for a domain.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | domain | string |The domain to find a default domain whitelabel for. | + operationId: Get the default domain whitelabel. consumes: - application/json produces: - application/json - operationId: A list of scopes for which that user has access. - summary: '' - description: '' - security: - - {} - /mail_settings/bcc: - parameters: [] - patch: + parameters: [] responses: '200': description: '' schema: - type: object - properties: - email: - type: string - enabled: - type: boolean - examples: - application/json: - email: example@example.com - enabled: false - parameters: [] + $ref: '#/definitions/whitelabel:domain_spf' + summary: '' + security: + - Authorization: [] + '/whitelabel/domains/{id}/ips/{ip}': + parameters: + - name: id + in: path + required: true + type: string + - name: ip + in: path + required: true + type: string + delete: + description: |- + **This endpoint allows you to remove a domain's IP address from that domain's whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer | ID of the domain whitelabel to delete the IP from. | + | ip | string | IP to remove from the domain whitelabel. | + operationId: Remove an IP from a domain whitelabel. consumes: - application/json produces: - application/json - operationId: Update BCC mail settings - summary: '' - description: '' - security: - - {} - get: + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_bcc' + $ref: '#/definitions/whitelabel:domain_spf' examples: application/json: - email: example@example.com - enabled: false - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get BCC mail settings + id: 1 + domain: example.com + subdomain: mail + username: mail@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false summary: '' - description: '' security: - - {} - '/whitelabel/domains/{domain_id}': - parameters: [] - delete: - responses: - '204': - description: '' - parameters: [] - consumes: - - application/json - produces: [] - operationId: Delete a domain whitelabel. - summary: '' + - Authorization: [] + '/templates/{template_id}/versions/{version_id}': + parameters: + - name: template_id + in: path + required: true + type: string + - name: version_id + in: path + required: true + type: string + get: description: |- - **This endpoint allows you to delete a domain whitelabel.** + **This endpoint allows you to retrieve a specific version of a template.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). ## URI Parameters - | URI Parameter | Type | Description | + | URI Parameter | Type | Description | |---|---|---| - | id | integer | The ID of the domain whose whitelabel you want to delete. | - security: - - {} - get: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/whitelabel::domain' - parameters: - - type: integer - description: "The ID of the domain you're whitelabeling." - name: id - in: query - required: true + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: Retrieve a specific transactional template version. consumes: - application/json produces: - application/json - operationId: Retrieve a domain whitelabel. + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + id: + type: string + description: The ID of the template version. + updated_at: + type: string + description: The date and time that the template version was last updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' + required: + - id + - updated_at + examples: + application/json: + id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f + template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d + active: 1 + name: version 1 name + html_content: '<%body%>' + plain_content: '<%body%>' + subject: '<%subject%>' + updated_at: '2014-03-19 18:56:33' summary: '' + security: + - Authorization: [] + delete: description: |- - **This endpoint allows you to retrieve a specific domain whitelabel.** + **This endpoint allows you to delete one of your transactional template versions.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). ## URI Parameters - | URI Parameter | Type | Description | + | URI Parameter | Type | Description | |---|---|---| - | id | integer | The ID of the whitelabeled domain. | - security: - - {} - patch: + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: Delete a transactional template version. + consumes: + - application/json + produces: [] + parameters: [] responses: - '200': + '204': description: '' schema: - title: Update a Domain response - type: object - properties: - default false: - description: Inidcates whether this domain whitelabel should be considered the default. Defaults to false. - type: boolean - custom_spf false: - description: Indicates whether to generate a custom SPF record for manual security. Defaults to false. - type: boolean - parameters: - - type: string - name: default - in: formData - description: Indicates whether this domain whitelabel should be considered the default. - - type: string - name: custom_spf - in: formData - description: Indicates whether to generate a custom SPF record for manual security. - consumes: - - application/json - produces: - - application/json - operationId: Update a domain whitelabel. + type: 'null' summary: '' + security: + - Authorization: [] + patch: description: |- - **This endpoint allows you to update the settings for a domain whitelabel.** + **This endpoint allows you to edit a version of one of your transactional templates.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). ## URI Parameters - | URI Parameter | Type | Description | + | URI Parameter | Type | Description | |---|---|---| - | id | integer | The ID of the domain you're whitelabeling. | - security: - - {} - /mail_settings/address_whitelist: - parameters: [] - patch: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_bounce_purge' - examples: - application/json: - enabled: false - list: - - example.com - parameters: - - type: string - name: enabled - in: formData - description: '' - - type: string - name: list - in: formData - description: '' + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: Edit a transactional template version. consumes: - application/json produces: - application/json - operationId: Update address whitelist mail settings - summary: '' - description: '' - security: - - {} - get: + parameters: + - name: body + in: body + schema: + type: object + properties: + active: + type: integer + description: Indicates if the template version is active. + name: + type: string + description: The name of the template version. + html_content: + type: string + description: The HTML content of the template version. + plain_content: + type: string + description: The text/plain content of the template version. + subject: + type: string + description: The subject of the template version. responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_address_whitelabel' + type: object + properties: + id: + type: string + description: The ID of the template version. + updated_at: + type: string + description: The date and time that the template version was last updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' + required: + - id + - updated_at examples: application/json: - enabled: false - list: - - example.com - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get address whitelist mail settings + id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f + template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d + active: 1 + name: version 1 name + html_content: '<%body%>' + plain_content: '<%body%>' + subject: '<%subject%>' + updated_at: '2014-03-19 18:56:33' summary: '' - description: '' security: - - {} - '/asm/groups/{group_id}': - parameters: [] - delete: - responses: - '204': - description: '' - schema: - type: object - properties: {} - parameters: [] + - Authorization: [] + '/templates/{template_id}/versions/{version_id}/activate': + parameters: + - name: template_id + in: path + required: true + type: string + - name: version_id + in: path + required: true + type: string + post: + description: |- + **This endpoint allows you to activate a version of one of your templates.** + + Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + + + For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | template_id | string | The ID of the original template | + | version_id | string | The ID of the template version | + operationId: Activate a transactional template version. consumes: - application/json produces: - application/json - operationId: Delete a suppression group. - summary: A single suppression group object with all its details - description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. - - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. - security: - - {} - get: + parameters: [] responses: '200': description: '' @@ -1216,234 +1215,367 @@ paths: type: object properties: id: - type: number - name: - type: string - description: type: string - last_email_sent_at: - type: 'null' - is_default: - type: boolean - unsubscribes: - type: number + description: The ID of the template version. + updated_at: + type: string + description: The date and time that the version was last updated. + Transactional Template Version: + $ref: '#/definitions/transactional_template_version' + required: + - id + - updated_at examples: application/json: - id: 100 - name: Newsletters - description: Our monthly newsletter. - last_email_sent_at: null - is_default: true - unsubscribes: 400 - parameters: [] + id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 + template_id: e3a61852-1acb-4b32-a1bc-b44b3814ab78 + active: 1 + name: example_version_name + html_content: '<%body%>' + plain_content: '<%body%>' + subject: '<%subject%>' + updated_at: '2014-06-12 11:33:00' + summary: '' + security: + - Authorization: [] + '/ips/pools/{pool_name}': + parameters: + - name: pool_name + in: path + required: true + type: string + get: + description: '' + operationId: List the IPs in a specified pool. consumes: - application/json produces: - application/json - operationId: Get information on a single suppression group. - summary: You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the “one-cl - description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. - - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. - security: - - {} - /tracking_settings/open: - parameters: [] - get: + parameters: [] responses: '200': description: '' schema: type: object properties: - enabled: - type: boolean - examples: - application/json: - enabled: true + pool_name: + type: string + ips: + type: array + items: + type: string + summary: '' + security: + - Authorization: [] + delete: + description: '' + operationId: Delete an IP pool. + consumes: + - application/json + produces: [] parameters: [] + responses: + '204': + description: '' + schema: + type: object + properties: {} + summary: '' + security: + - Authorization: [] + put: + description: '' + operationId: Update an IP pool’s name. consumes: - application/json produces: - application/json - operationId: Get Open Tracking Settings - summary: '' - description: '' - security: - - {} - patch: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/ip_pool' responses: '200': description: '' schema: - type: object - properties: - enabled: - type: boolean + $ref: '#/definitions/ip_pool' examples: application/json: - enabled: true - parameters: - - type: string - name: enabled - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Update Open Tracking Settings + name: new_pool_name summary: '' - description: '' security: - - {} - '/whitelabel/links/{id}': - parameters: [] - delete: - responses: - '204': - description: '' - parameters: [] + - Authorization: [] + '/whitelabel/domains/{domain_id}/subuser': + parameters: + - name: domain_id + in: path + required: true + type: string + post: + description: |- + **This endpoint allows you to associate a specific domain whitelabel with a subuser.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | domain_id | integer | ID of the domain whitelabel to associate with the subuser. | + operationId: Associate a domain whitelabel with a given user. consumes: - application/json - produces: [] - operationId: Delete a Link - summary: '' - description: '' - security: - - {} - patch: - responses: - '200': - description: '' + produces: + - application/json + parameters: + - name: body + in: body schema: type: object properties: - id: - type: integer - domain: - type: string - subdomain: - type: string username: type: string - user_id: - type: integer - default: - type: boolean - valid: - type: boolean - legacy: - type: boolean - dns: - type: object - properties: - domain_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - owner_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string + description: Username to associate with the domain whitelabel. + required: + - username + responses: + '201': + description: '' + schema: + $ref: '#/definitions/whitelabel:domain_spf' examples: application/json: id: 1 domain: example.com subdomain: mail - username: john@example.com + username: mail@example.com user_id: 7 - default: true - valid: true + ips: [] + custom_spf: true + default: false legacy: false + automatic_security: false + valid: false dns: - domain_cname: - valid: true - type: cname + mail_server: host: mail.example.com + type: mx data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - parameters: - - type: string - name: default - in: formData - description: '' + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false + summary: '' + security: + - Authorization: [] + /whitelabel/domains/subuser: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | username | string | Username of the subuser to find associated whitelabels for. | + operationId: List the domain whitelabel associated with the given user. consumes: - application/json produces: - application/json - operationId: Update a Link - summary: '' - description: '' - security: - - {} - get: + parameters: [] responses: '200': description: '' schema: - type: object - properties: - id: - type: integer - domain: - type: string - subdomain: - type: string - username: - type: string - user_id: - type: integer - default: - type: boolean - valid: - type: boolean - legacy: - type: boolean + $ref: '#/definitions/whitelabel:domain_spf' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: mail@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false dns: - type: object - properties: - domain_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - owner_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false + summary: '' + security: + - Authorization: [] + delete: + description: |- + **This endpoint allows you to disassociate a specific whitelabel from a subuser.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + | username | string | required | Username for the subuser to find associated whitelabels for. | + operationId: Disassociate a domain whitelabel from a given user. + consumes: + - application/json + produces: [] + parameters: [] + responses: + '204': + description: '' + summary: |- + Domain Whitelabels can be associated with subusers via parent accounts. This functionality allows + subusers to send mail + security: + - Authorization: [] + '/whitelabel/domains/{id}/ips': + parameters: + - name: id + in: path + required: true + type: string + post: + description: |- + **This endpoint allows you to add an IP address to a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer | ID of the domain to which you are adding an IP | + operationId: Add an IP to a domain whitelabel. + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + ip: + type: string + description: IP to associate with the domain. Used for manually specifying IPs for custom SPF. + required: + - ip + responses: + '200': + description: '' + schema: + $ref: '#/definitions/whitelabel:domain_spf' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false + summary: '' + security: + - Authorization: [] + '/whitelabel/links/{id}': + parameters: + - name: id + in: path + description: The id of the link whitelabel you want to retrieve. + required: true + type: integer + get: + description: |- + **This endpoint allows you to retrieve a specific link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Retrieve a Link Whitelabel + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/link_whitelabel' examples: application/json: id: 1 @@ -1465,1002 +1597,785 @@ paths: type: cname host: 7.example.com data: sendgrid.net + summary: '' + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Update a Link Whitelabel + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + default: + type: boolean + description: 'Indicates if the link whitelabel is set as the default, or fallback, whitelabel.' + enum: + - true + - false + responses: + '200': + description: '' + schema: + $ref: '#/definitions/link_whitelabel' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: true + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + summary: '' + security: + - Authorization: [] + delete: + description: |- + **This endpoint allows you to delete a link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Delete a Link Whitelabel + consumes: + - application/json + produces: [] parameters: [] + responses: + '204': + description: '' + summary: '' + security: + - Authorization: [] + '/whitelabel/domains/{domain_id}': + parameters: + - name: id + in: path + description: The id of the domain whitelabel. + required: true + type: number + patch: + description: |- + **This endpoint allows you to update the settings for a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: Update a domain whitelabel. consumes: - application/json produces: - application/json - operationId: Retrieve a Link + parameters: + - name: body + in: body + schema: + type: object + properties: + default: + type: boolean + default: 'false' + description: Indicates whether this domain whitelabel should be considered the default. + custom_spf: + type: boolean + default: 'false' + description: Indicates whether to generate a custom SPF record for manual security. + responses: + '200': + description: '' + schema: + title: Update a Domain response + type: object + properties: + default false: + description: Inidcates whether this domain whitelabel should be considered the default. Defaults to false. + type: boolean + custom_spf false: + description: Indicates whether to generate a custom SPF record for manual security. Defaults to false. + type: boolean summary: '' - description: '' security: - - {} - /devices/stats: - parameters: [] + - Authorization: [] get: + description: | + **This endpoint allows you to retrieve a specific domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: Retrieve a domain whitelabel. + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - date: - type: string - stats: - type: array - items: - properties: - type: - type: string - name: - type: string - metrics: - type: object - properties: - opens: - type: number - unique_opens: - type: number - examples: - application/json: - - date: '2015-10-11' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-12' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-13' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-14' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-15' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-16' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-17' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-18' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-19' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-20' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-21' - stats: - - type: device - name: Webmail - metrics: - opens: 1 - unique_opens: 1 - - date: '2015-10-22' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-23' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-24' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-25' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-26' - stats: - - type: device - name: Webmail - metrics: - opens: 2 - unique_opens: 2 - - date: '2015-10-27' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-28' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-29' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-30' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-10-31' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-01' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-02' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-03' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-04' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-05' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-06' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-07' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-08' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-09' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - - date: '2015-11-10' - stats: - - type: device - name: Webmail - metrics: - opens: 0 - unique_opens: 0 - parameters: - - type: string - name: end_date - in: query - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query - - type: string - name: start_date - in: query + $ref: '#/definitions/whitelabel::domain' + summary: '' + security: + - Authorization: [] + delete: + description: |- + **This endpoint allows you to delete a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: Delete a domain whitelabel. consumes: - application/json - produces: - - application/json - operationId: Gets email statistics by device type. + produces: [] + parameters: [] + responses: + '204': + description: '' summary: '' - description: '' security: - - {} - /mailbox_providers/stats: + - Authorization: [] + /contactdb/lists: parameters: [] + delete: + description: |- + Delete multiple lists. + + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Delete Multiple lists + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '204': + description: '' + schema: + type: 'null' + '400': + description: '"id" : "Returned if all list ids are not valid"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: list id was invalid + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: '' + security: + - Authorization: [] + post: + description: |- + Create a list for your recipients. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Create a List + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + title: Create a List request + type: object + properties: + name: + type: string + required: + - name + responses: + '201': + description: '' + schema: + $ref: '#/definitions/contactdb_list' + examples: + application/json: + id: 1 + name: your list name + recipient_count: 0 + '400': + description: |- + "name" : "Returned if list name is a duplicate of an existing list or segment" + "name" : "Returned if list name is not a string" + "" : "Returned if request body is invalid JSON" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: Returned if request body is invalid JSON + - field: name + message: Returned if list name is not a string + - field: name + message: Returned if list name is a duplicate of an existing list or segment + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: '' + security: + - Authorization: [] get: + description: |- + Returns an empty list if you GET and no lists exist on your account. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: List All Lists + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - date: - type: string - stats: - type: array - items: - properties: - type: - type: string - name: - type: string - metrics: - type: object - properties: - blocks: - type: number - bounces: - type: number - clicks: - type: number - deferred: - type: number - delivered: - type: number - drops: - type: number - opens: - type: number - spam_reports: - type: number - unique_clicks: - type: number - unique_opens: - type: number + title: List All Lists response + type: object + properties: + lists: + type: array + items: + $ref: '#/definitions/contactdb_list' + required: + - lists examples: application/json: - - date: '2015-10-11' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-12' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-13' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-14' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-15' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-16' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-17' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-18' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-19' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-20' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-21' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 1 - drops: 0 - opens: 1 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 1 - - date: '2015-10-22' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-23' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-24' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-25' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-26' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 2 - drops: 0 - opens: 2 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 2 - - date: '2015-10-27' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-28' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-29' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-30' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-31' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-01' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-02' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-03' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-04' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-05' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-06' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-07' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-08' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-09' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-10' - stats: - - type: mailbox_provider - name: Gmail - metrics: - blocks: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - drops: 0 - opens: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 + lists: + - id: 1 + name: the jones + recipient_count: 1 + summary: Returns an empty list if you GET and no lists exist on your account. + security: + - Authorization: [] + '/subusers/{subuser_name}/monitor': + parameters: + - name: subuser_name + in: path + required: true + type: string + post: + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: Create monitor settings + consumes: + - application/json + produces: + - application/json parameters: - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query + - name: body + in: body + schema: + $ref: '#/definitions/monitor' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/monitor' + examples: + application/json: + email: example@example.com + frequency: 50000 + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: User already has a monitor + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: '' + security: + - Authorization: [] + delete: + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: Delete monitor settings consumes: - application/json produces: - application/json - operationId: Gets email statistics by mailbox provider. + parameters: [] + responses: + '204': + description: '' + schema: + type: object + properties: {} + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: No monitor settings for this user + summary: '' + put: + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: Update Monitor Settings for a subuser + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/monitor' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/monitor' + examples: + application/json: + email: example@example.com + frequency: 500 + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: email + message: Email is required + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required summary: '' - description: '' security: - - {} - '/ips/{ip_address}': - parameters: [] + - Authorization: [] get: - responses: {} + description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + operationId: Retrieve monitor settings for a subuser + consumes: + - application/json + produces: + - application/json parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/monitor' + examples: + application/json: + email: example@example.com + frequency: 500 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: No monitor settings for this user + summary: '' + security: + - Authorization: [] + '/whitelabel/links/{link_id}/subuser': + parameters: + - name: link_id + in: path + description: The id of the link whitelabel you want to associate. + required: true + type: integer + post: + description: |- + **This endpoint allows you to associate a link whitelabel with a subuser account.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Associate a Link Whitelabel consumes: - application/json - produces: [] - operationId: See which pools an IP address belongs to. - summary: '' - description: '' - security: - - {} - '/ips/pools/{pool_name}/ips': - parameters: [] - post: - responses: {} + produces: + - application/json parameters: - - type: string - name: ip - in: formData + - name: body + in: body + schema: + type: object + properties: + username: + type: string + description: The username of the subuser account that you want to associate the link whitelabel with. + responses: + '200': description: '' - consumes: - - application/json - produces: [] - operationId: Assign an IP to a pool + schema: + $ref: '#/definitions/link_whitelabel' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net summary: '' - description: '' security: - - {} - '/whitelabel/ips/{id}': + - Authorization: [] + /whitelabel/links/subuser: parameters: [] get: + description: |- + **This endpoint allows you to retrieve the associated link whitelabel for a subuser.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Retrieve Associated Link Whitelabel + consumes: + - application/json + produces: + - application/json + parameters: + - name: username + in: query + description: The username of the subuser to retrieve associated link whitelabels for. + required: true + type: string responses: '200': description: '' schema: - type: object - properties: - ip: - type: string - rdns: - type: string - users: - type: array - items: - type: object - properties: - username: - type: string - user_id: - type: integer - subdomain: - type: string - domain: - type: string - valid: - type: boolean - legacy: - type: boolean - a_record: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string + $ref: '#/definitions/link_whitelabel' examples: application/json: - ip: 192.168.1.1 - rdns: o1.email.example.com - users: - - username: john@example.com - user_id: 7 - subdomain: email + id: 1 domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false valid: true legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.1 - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Retrieve an IP + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net summary: '' - description: '' security: - - {} + - Authorization: [] delete: - responses: - '204': - description: '' - schema: - type: object - properties: {} - parameters: [] + description: |- + **This endpoint allows you to disassociate a link whitelabel from a subuser.** + + Link whitelables can be associated with subusers from the parent account. This functionality allows + subusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account + must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Disassociate a Link Whitelabel consumes: - application/json produces: [] - operationId: Delete an IP - summary: '' - description: '' + parameters: + - name: username + in: query + description: The username of the subuser account that you want to disassociate a link whitelabel from. + required: true + type: string + responses: + '204': + description: '' + summary: |- + Link Whitelabels can be associated with subusers via parent accounts. This functionality allows + subusers to send mail o security: - - {} - /tracking_settings/click: + - Authorization: [] + /contactdb/segments: parameters: [] - patch: + get: + description: |- + Get all your segments. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: List All Segments + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '200': description: '' schema: + title: List All Segments response type: object properties: - enable_text: - type: boolean - enabled: - type: boolean + segments: + type: array + items: + $ref: '#/definitions/contactdb_segments' + required: + - segments examples: application/json: - enable_text: false - enabled: true - parameters: - - type: string - name: enabled - in: formData + segments: + - id: 1234 + name: Age segments < 25 + conditions: + - field: age + value: '25' + operator: lt + recipient_count: 8 + - id: 2345 + name: email address - gmail + conditions: + - field: email + value: '@gmail.com' + operator: contains + recipient_count: 0 + '401': description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: '' + security: + - Authorization: [] + post: + description: "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. \n\nSegments may contain multiple condtions, joined by an \"and\" or \"or\" in the \"and_or\" field. The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." + operationId: Create a Segment consumes: - application/json produces: - application/json - operationId: Update Click Tracking Settings - summary: '' - description: '' - security: - - {} - get: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/contactdb_segments' responses: '200': description: '' schema: - type: object - properties: - enable_text: - type: boolean - enabled: - type: boolean + $ref: '#/definitions/contactdb_segments_with_id' + examples: + application/json: + id: 1 + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + - field: last_clicked + value: 01/02/2015 + operator: gt + and_or: and + - field: clicks.campaign_identifier + value: '513' + operator: eq + and_or: or + recipient_count: 0 + '400': + description: |- + "name" : "Returned if the name is not valid" + "list_id" : "Returned if the list_id is not valid" + "and_or" : "Returned if and_or and set value is not passed into the request body" + "and_or" : "Returned if and_or is set on the only condition passed" + "and_or" : "Returned if and_or is set on all conditions" + "and_or" : "Returned if and_or is not set on more than one condition and less than all conditions" + "operator" : "Returned if operator and set value is not passed into the request body" + "value" : "Returned if value and set value is not passed into the request body" + "field" : "Returned if field and set value is not passed into the request body" + "" : "Returned if request body is not valid json" + "" : "Returned if invalid value is passed into one of the request body parameters" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: request body is not valid json + - message: invalid value is passed into one of the request body parameters + - field: field + message: field and set value is not passed into the request body + - field: value + message: value and set value is not passed into the request body + - field: operator + message: operator and set value is not passed into the request body + - field: and_or + message: and_or is not set on more than one condition and less than all conditions + - field: and_or + message: and_or is set on all conditions + - field: and_or + message: and_or is set on the only condition passed + - field: and_or + message: and_or and set value is not passed into the request body + - field: list_id + message: the list_id is not valid + - field: name + message: the name is not valid + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - enable_text: false - enabled: true - parameters: [] + errors: + - field: null + message: authorization required + summary: '' + security: + - Authorization: [] + '/contactdb/segments/{segment_id}': + parameters: + - name: segment_id + in: path + required: true + type: string + delete: + description: |- + Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Delete a Segment consumes: - application/json produces: - application/json - operationId: Get Click Track Settings - summary: '' - description: '' - security: - - {} - '/api_keys/{api_key_id}': - parameters: [] - delete: + parameters: + - name: delete_contacts + in: query + description: True to delete all contacts matching the segment in addition to deleting the segment + type: boolean responses: '204': description: '' schema: type: 'null' - '404': + '400': + description: |- + "segment_id" : "Returned if segment_id is not valid" + "delete_contacts" : "Returned if delete_contacts is not a valid boolean" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: segment_id + message: Returned if segment_id is not valid + - field: delete_contacts + message: Returned if delete_contacts is not a valid boolean + '401': description: '' schema: $ref: '#/definitions/global:ErrorResponse' @@ -2468,116 +2383,215 @@ paths: application/json: errors: - field: null - message: unable to find API Key - parameters: [] + message: authorization required + '404': + description: '"segment_id" : "Returned if segment_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: segment_id + message: segment_id does not exist + summary: '' + security: + - Authorization: [] + get: + description: |- + Get a single segment by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Retrieve a Segment consumes: - application/json produces: - application/json - operationId: Delete API keys - summary: |- - **Revoke an existing API Key** - - Authentications using this API Key will fail after this request is made, with some small - description: |- - **Revoke an existing API Key** - - Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters - - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are deleting.| - security: - - {} - put: + parameters: + - name: segment_id + in: query + description: The ID of the segment you want to request. + required: true + type: number responses: '200': description: '' schema: - $ref: '#/definitions/api_key_name_id_scopes' + $ref: '#/definitions/contactdb_segments' examples: application/json: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - scopes: - - user.profile.read - - user.profile.update + id: 1 + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + recipient_count: 1 '400': - description: Unexpected error in API call. See HTTP response body for details. + description: '"segment_id" : "Returned if segment_id is not valid"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: "expected JSON request body with 'name' property" + - message: if segment_id is not valid '401': description: '' schema: - type: object - properties: {} + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required '404': - description: Unexpected error in API call. See HTTP response body for details. + description: '"segment_id" : "Returned if segment_id does not exist"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: unable to find API Key to update + - message: segment_id not found + summary: '' + security: + - Authorization: [] + patch: + description: |- + Update a segment. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Update a segment + consumes: + - application/json + produces: + - application/json parameters: - - type: string - name: name - in: formData + - name: segment_id + in: query + description: The ID of the segment you are updating. + type: string + - name: body + in: body + schema: + type: object + properties: + name: + type: string + list_id: + type: number + description: The list ID you would like this segment to be built from. + conditions: + type: array + description: The conditions by which this segment should be created. + items: + $ref: '#/definitions/contactdb_segments_conditions' + required: + - name + responses: + '200': description: '' - - type: string - name: scopes - in: formData + schema: + $ref: '#/definitions/contactdb_segments' + examples: + application/json: + id: 5 + name: The Millers + list_id: 5 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + recipient_count: 1 + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: request body is not valid json + - message: invalid value is passed into one of the request body parameters + - segment_id: segment_id + message: segment id is not valid + - field: field + message: field and set value is not passed into the request body + - field: value + message: value and set value is not passed into the request body + - field: operator + message: operator and set value is not passed into the request body + - field: and_or + message: and_or is not set on more than one condition and less than all conditions + - field: and_or + message: and_or is set on all conditions + - field: and_or + message: and_or is set on the only condition passed + - field: and_or + message: and_or and set value is not passed into the request body + - field: list_id + message: the list_id is not valid + - field: name + message: the name is not valid + '401': description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: '' + security: + - Authorization: [] + '/contactdb/recipients/{recipient_id}/lists': + parameters: + - name: recipient_id + in: path + required: true + type: string + get: + description: |- + Each recipient can be on many lists. This endpoint gives you the lists this recipient is associated to. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Get the Lists the Recipient Is On consumes: - application/json produces: - application/json - operationId: 'Update the name & scopes of an API Key' - summary: |- - A JSON request body with a "name" property is required. - Most provide the list of all the scopes an api key should have. - description: |- - A JSON request body with a "name" property is required. - Most provide the list of all the scopes an api key should have. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters - - | Param | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are updating.| - security: - - {} - get: + parameters: + - name: recipient_id + in: query + description: The ID of the recipient you are requesting lists for. + required: true + type: string responses: '200': description: '' schema: - type: object - properties: - result: - type: array - _isOpen: true - items: - $ref: '#/definitions/api_key_name_id_scopes' + type: object + properties: + lists: + type: array + items: + $ref: '#/definitions/contactdb_list' + examples: + application/json: + lists: + - id: 1234 + name: Example list + recipient_count: 42 + '400': + description: '"recipient_id" : "Returned if recipient_id is not valid"' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id + errors: + - field: null + message: recipient ID is invalid '401': description: '' schema: @@ -2588,55 +2602,54 @@ paths: - field: null message: authorization required '404': - description: Unexpected error in API call. See HTTP response body for details. + description: '"recipient_id" : "Returned if record for the recipient id does not exist"' schema: - type: object - properties: {} + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: unable to find API Key - parameters: - - type: string - name: name - in: formData - required: true - description: The name you will use to describe this API Key. - - type: string - name: scopes - in: formData - required: false - description: The individual permissions that you are giving to this API Key. + message: recipient id not found + summary: '' + security: + - Authorization: [] + '/contactdb/recipients/{recipient_id}': + parameters: + - name: recipient_id + in: path + required: true + type: string + delete: + description: |- + Delete a single recipient from your contact database, by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Delete a Recipient consumes: - application/json produces: - application/json - operationId: Get an existing API Key - summary: |- - Retrieve a single api key. - If the API Key ID does not exist an HTTP 404 will be returned. - description: |- - Retrieve a single api key. - If the API Key ID does not exist an HTTP 404 will be returned. - - ## URI Parameters - - | Param | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key for which you are requesting information.| - security: - - {} - patch: + parameters: + - name: recipient_id + in: query + description: The ID of the recipient to be deleted. + required: true + type: string responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/api_key_name_id' + type: object + properties: {} + '400': + description: '"recipient_id" : "Returned if recipient_id is not valid"' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope + errors: + - field: null + message: recipient not found '401': description: '' schema: @@ -2646,221 +2659,117 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - name: name - in: formData - description: The new name of the API Key. - consumes: - - application/json - produces: - - application/json - operationId: Update API keys - summary: |- - **Update the name of an existing API Key** - - A JSON request body with a "name" property is required. - - The API Keys featur - description: |- - **Update the name of an existing API Key** - - A JSON request body with a "name" property is required. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters - - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are updating.| + '404': + description: '"recipient_id" : "Returned if record for recipient id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: recipient_id is not valid + summary: '' security: - - {} - /user/settings/enforced_tls: - parameters: [] + - Authorization: [] get: - responses: {} - parameters: [] + description: |- + Retrieve a single recipient by ID from your contact database. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Retrieve a single recipient consumes: - application/json - produces: [] - operationId: Get the current Enforced TLS settings. - summary: '' - description: '' - security: - - {} - patch: - responses: {} - parameters: - - type: string - name: require_tls - in: formData - description: '' - - type: string - name: require_valid_cert - in: formData - description: '' - consumes: + produces: - application/json - produces: [] - operationId: Change the Enforced TLS settings - summary: '' - description: '' - security: - - {} - /subusers/reputations: - parameters: [] - get: + parameters: + - name: recipient_id + in: query + description: The ID of the created recipient. + type: string responses: '200': description: '' schema: - type: array - items: - type: object - properties: - reputation: - type: number - description: The sender reputation this subuser has attained. - username: - type: string - description: The subuser that has this reputation.f - required: - - reputation - - username - examples: - application/json: - - username: example_subuser - reputation: 99 - - username: example_subuser2 - reputation: 95.2 + $ref: '#/definitions/contactdb_recipient' + '400': + description: '"recipient_id" : "Returned if recipient_id is not valid"' '401': description: '' schema: - type: object - properties: {} - parameters: - - type: string - name: subuser_name - in: query - consumes: - - application/json - produces: - - application/json - operationId: Retrieve Subuser Reputations + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"recipient_id" : "Returned if record for recipient id does not exist"' summary: '' - description: |- - Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will effect your sender rating. - - This endpoint allows you to request the reputations for your subusers. security: - - {} - /user/profile: + - Authorization: [] + /contactdb/recipients/search: parameters: [] get: - responses: - '200': - description: '' - schema: - title: GET User Profile response - type: object - properties: - address: - type: string - description: "The user's address." - address2: - type: string - description: "The second line of the user's address." - city: - type: string - description: "The user's city." - company: - type: string - description: "The name of the user's company." - country: - type: string - description: "The user's country." - first_name: - type: string - description: "The user's first name." - last_name: - type: string - description: "The user's last name." - phone: - type: string - description: "The user's phone number." - state: - type: string - description: "The user's state." - website: - type: string - description: "The user's website URL." - zip: - type: string - description: "The user's zip code." - required: - - address - - city - - company - - country - - first_name - - last_name - - phone - - state - - website - - zip - examples: - application/json: - address: 814 West Chapman Avenue - address2: '' - city: Orange - company: SendGrid - country: US - first_name: Test - last_name: User - phone: 555-555-5555 - state: CA - website: 'http://www.sendgrid.com' - zip: '92868' - '401': - description: '' - schema: - type: object - properties: {} - parameters: [] + description: |- + Search the recipients in your contactdb. + + field_name: + + * is a variable that is substituted for your actual custom field name from your recipient. + * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) + * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert + your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to + Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through + Mon, 02 Feb 2015 23:59:59 GMT. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Get Recipients Matching Search Criteria consumes: - application/json produces: - application/json - operationId: "Get a user's profile" - summary: '' - description: |- - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: - - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - security: - - {} - patch: + parameters: + - name: '{field_name}' + in: query + type: string responses: '200': description: '' schema: - $ref: '#/definitions/user_profile' + type: object + properties: + recipients: + type: array + items: + $ref: '#/definitions/contactdb_recipient' examples: application/json: - address: 814 West Chapman Avenue - address2: '' - city: Orange - company: SendGrid - country: US - first_name: Example - last_name: User - phone: 555-555-5555 - state: CA - website: 'http://www.sendgrid.com' - zip: '92868' + recipients: + - created_at: 1422313607 + email: jones@example.com + first_name: null + id: YUBh + last_clicked: null + last_emailed: null + last_name: Jones + last_opened: null + updated_at: 1422313790 + custom_fields: + - id: 23 + name: pet + value: Fluffy + type: text + '400': + description: |- + "" : "Returned if no search params are specified" + "field" : "Returned if the provided field is invalid or does not exist" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]' + - message: No search params are specified '401': description: '' schema: @@ -2870,44 +2779,39 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - description: "You can enter a subuser name as the value for this header, in order to update the subuser's profile." - name: on-behalf-of - in: header + summary: |- + {% info %} + "field_name"* is a variable that is substituted for your actual custom field name from your recipient. + Text f + security: + - Authorization: [] + /contactdb/recipients: + parameters: [] + delete: + description: |- + Deletes one or more recipients. The body is a list of recipient ids to delete. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Delete Recipient consumes: - application/json produces: - application/json - operationId: "Update a user's profile" - summary: '' - description: |- - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: - - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - - It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. - security: - - {} - '/user/scheduled_sends/{batch_id}': - parameters: [] - get: + parameters: [] responses: '200': description: '' + '400': + description: |- + "" : "Returned if no recipients are deleted" + "" : "Returned if all of the provided recipient ids are invalid" + "" : "Returned if request body is not valid json" schema: - type: array - title: Retrieve scheduled send response - items: - $ref: '#/definitions/user_scheduled_send_status' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi - status: cancel - - batch_id: IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg - status: pause + errors: + - message: No recipient ids provided '401': description: '' schema: @@ -2917,41 +2821,36 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - description: "The batch ID is the identifier that your scheduled mail sends share.\t" - pattern: '^[a-zA-Z0-9]' - name: batch_id - in: query + summary: Deletes one or more recipients. The body is a list of recipient ids to delete. + security: + - Authorization: [] + patch: + description: |- + Updates one or more recipients. The body is an array of recipient objects. + + It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Update Recipient consumes: - application/json produces: - application/json - operationId: Retrieve scheduled send - summary: |- - Get cancel/paused scheduled send information. If {batch_id} is omitted, all of the user's scheduled send cancellations - a - description: |- - Get cancel/paused scheduled send information for a specific batch_id. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - security: - - {} - patch: + parameters: [] responses: - '204': + '201': description: '' schema: - type: 'null' + $ref: '#/definitions/contactdb_recipient_response' '400': - description: '' + description: '"" : "Returned if request body is not valid json"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: status - message: status must be either cancel or pause + - field: null + message: Request body is not valid json '401': description: '' schema: @@ -2961,39 +2860,48 @@ paths: errors: - field: null message: authorization required - '404': - description: '"" : "batch id not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: batch id not found - parameters: - - type: string - name: status - in: formData - required: true - description: The status you would like the scheduled send to have. + summary: Updates one or more recipients. The body is a list of recipient objects. + security: + - Authorization: [] + get: + description: |- + Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of + the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: "List Recipients [waiting on Bryan Adamson's response]" consumes: - application/json produces: - application/json - operationId: Update user scheduled send information - summary: Update the status of a scheduled send. - description: |- - Update the status of a scheduled send. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - security: - - {} - delete: + parameters: + - name: page + in: query + description: Page index of first recipients to return (must be a positive integer) + type: integer + - name: page_size + in: query + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) + type: integer responses: - '204': + '200': description: '' schema: - type: 'null' + title: List Recipients response + type: object + properties: + recipients: + type: array + items: + type: object + required: + - recipients + '400': + description: |- + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" '401': description: '' schema: @@ -3003,54 +2911,50 @@ paths: errors: - field: null message: authorization required - '404': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: batch id not found - parameters: - - type: string - description: The batch ID with the cancel or pause that you would like to delete. - pattern: '^[a-zA-Z0-9]' - name: batch_id - in: query + summary: | + {% info %} + Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of + security: + - Authorization: [] + post: + description: |- + Add a recipient to your contactdb. It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Add recipients consumes: - application/json produces: - application/json - operationId: Delete a cancellation or pause of a scheduled send - summary: Delete the cancellation/pause of a scheduled send. - description: |- - Delete the cancellation/pause of a scheduled send. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - security: - - {} - /api_keys: - parameters: [] - get: + parameters: [] responses: - '200': + '201': description: '' schema: - type: object - properties: - result: - type: array - _isOpen: true - items: - $ref: '#/definitions/api_key_name_id' + $ref: '#/definitions/contactdb_recipient_response' + examples: + application/json: + error_count: 1 + error_indices: + - 2 + new_count: 2 + persisted_recipients: + - YUBh + - bWlsbGVyQG1pbGxlci50ZXN0 + updated_count: 0 + errors: + - message: Invalid email. + error_indices: + - 2 + '400': + description: '"" : "Returned if request body is not valid json"' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id + errors: + - field: null + message: Request body is not valid json '401': description: '' schema: @@ -3060,44 +2964,58 @@ paths: errors: - field: null message: authorization required - parameters: [] + summary: '' + security: + - Authorization: [] + '/contactdb/lists/{list_id}/recipients/{recipient_id}': + parameters: + - name: list_id + in: path + required: true + type: string + - name: recipient_id + in: path + required: true + type: string + delete: + description: |- + Delete a single recipient from a list. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Delete a Single Recipient from a Single List consumes: - application/json produces: - application/json - operationId: List all API Keys belonging to the authenticated user - summary: "**List all API Keys belonging to the authenticated user**\n\nThe API Keys feature allows customers to be able to generate " - description: 'The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).' - security: - - {} - post: + parameters: + - name: list_id + in: query + description: The ID of the list you are taking this recipient away from. + required: true + type: number + - name: recipient_id + in: query + description: The ID of the recipient to take off the list. + required: true + type: number responses: - '200': + '204': description: '' schema: - type: object - properties: - result: - type: array - _isOpen: true - items: - $ref: '#/definitions/api_key_name_id' - examples: - application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id + type: 'null' '400': - description: '' + description: |- + "list_id" : "Returned if list_id is not valid" + "recipient_id" : "Returned if recipient_id is not valid" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: name - message: missing required argument + - field: list_id + message: Returned if list_id is invalid + - field: recipient_id + message: no valid recipients were provided '401': description: '' schema: @@ -3107,263 +3025,126 @@ paths: errors: - field: null message: authorization required - '403': - description: '' + '404': + description: |- + "list_id" : "Returned if list_id does not exist" + "recipient_id" : "Returned if recipient_id does not exist" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: Cannot create more than 100 API Keys - parameters: - - type: string - name: name - in: formData - required: true - description: The name you will use to describe this API Key. - - type: string - name: scopes - in: formData - required: false - description: The individual permissions that you are giving to this API Key. + - field: list_id + message: Returned if list_id does not exist + - field: recipient_id + message: Returned if recipient_id does not exist + summary: '' + security: + - Authorization: [] + post: + description: |- + Add a recipient to a list. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Add a Single Recipient to a List consumes: - application/json produces: - application/json - operationId: Create API keys - summary: |- - **Generate a new API Key for the authenticated user** - - This will create a new random API Key for the user. A JSON reques - description: |- - This will create a new random API Key for the user. A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. - - There is a limit of 100 API Keys on your account. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. - security: - - {} - /campaigns: - parameters: [] - get: - responses: - '200': - description: '' - schema: - type: object - properties: - result: - type: array - _isOpen: true - items: - $ref: '#/definitions/campaign_response' - examples: - application/json: - result: - - id: 986724 - title: March Newsletter - subject: 'New Products for Spring!' - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content: '

Check out our spring line!

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

Last call for winter clothes!

' - plain_content: 'Last call for winter clothes!' - status: Sent parameters: - - type: number - default: 10 - description: The number of results you would like to receive at a time. - name: limit + - name: list_id in: query - - type: number - default: '0' - description: 'The index of the first campaign to return, where 0 is the first campaign.' - name: offset + description: The ID of the list to add the recipient to. + type: number + - name: recipient_id in: query - consumes: - - application/json - produces: - - application/json - operationId: Get all Campaigns - summary: |- - Returns campaigns in reverse order they were created (newest first) - Returns an empty array if no campaigns exist - description: |- - Returns campaigns in reverse order they were created (newest first). - - Returns an empty array if no campaigns exist. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - post: + description: The recipient you are adding to the list indicated. + type: string responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/campaign_response' - examples: - application/json: - id: 986724 - title: March Newsletter - subject: 'New Products for Spring!' - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content: '

Check out our spring line!

' - plain_content: 'Check out our spring line!' - status: Draft + type: 'null' '400': description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + "list_id" : "Returned if list_id is invalid" + "recipient_id" : "Returned if recipient_id is invalid" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: title - message: "title can't be blank" - - field: title - message: title is too long (maximum is 100 characters) - - field: categories - message: categories exceeds 10 category limit - - field: html_content - message: html_content exceeds the 1MB limit - - field: plain_content - message: plain_content exceeds the 1MB limit - - field: sender_id - message: sender_id does not exist - - field: sender_id - message: sender_id is not a verified sender identity - - field: list_ids - message: list_ids do not all exist - - field: segment_ids - message: segment_ids do not all exist - - field: ip_pool - message: The ip pool you provided is invalid - - field: suppression_group_id - message: suppression_group_id does not exist - - field: unsubscribes - message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: "You've reached your limit of 250 campaigns. Please delete one or more and try again." + - field: list_id + message: Returned if list_id is invalid + - field: recipient_id + message: Returned if recipient_id is invalid '401': description: '' schema: - type: object - properties: {} - parameters: [] + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: |- + "list_id" : "Returned if list_id does not exist" + "recipient_id" : "Returned if recipient_id does not exist" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: list_id + message: Returned if list_id does not exist + - field: recipient_id + message: Returned if recipient_id does not exist + summary: '' + security: + - Authorization: [] + '/contactdb/lists/{list_id}': + parameters: + - name: list_id + in: path + required: true + type: string + delete: + description: |- + Delete a list by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Delete a List consumes: - application/json produces: - application/json - operationId: Create a Campaign - summary: |- - {% info %} - A campaign requires a title to be created. - In order to send or schedule the campaign, you will be required to - description: |- - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - - Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - /contactdb/reserved_fields: - parameters: [] - get: + parameters: + - name: delete_contacts + in: query + description: Adds the ability to delete all contacts on the list in addition to deleting the list. + type: boolean + enum: + - true + - false responses: - '200': + '202': description: '' schema: - title: "List fields that are reserved and can't be used for custom field names. response" - type: object - properties: - reserved_fields: - type: array - description: The reserved fields that are already set up within custom fields. - items: - $ref: '#/definitions/contactdb_custom_field' - required: - - reserved_fields + type: 'null' + '400': + description: |- + "list_id" : "Returned if list_id is not valid" + "delete_contacts" : "Returned if delete_contacts is not valid" + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - reserved_fields: - - name: first_name - type: text - - name: last_name - type: text - - name: email - type: text - - name: created_at - type: date - - name: updated_at - type: date - - name: last_emailed - type: date - - name: last_clicked - type: date - - name: last_opened - type: date - - name: my_custom_field - type: text + errors: + - field: delete_contacts + message: delete_contacts not a bool + - field: list_id + message: Returned if list_id is not valid '401': description: '' schema: @@ -3373,1112 +3154,798 @@ paths: errors: - field: null message: authorization required - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get reserved custom fields fields. + '404': + description: '"list_id" : "Returned if list_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: 'List not found: 5' summary: '' + security: + - Authorization: [] + patch: description: |- - List fields that are reserved and can't be used for custom field names. [GET] + Update the name of a list. + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - '/campaigns/{campaign_id}/schedules': - parameters: [] - delete: + operationId: Update a List + consumes: + - application/json + produces: + - application/json + parameters: + - name: list_id + in: query + description: The ID of the list you are updating. + required: true + type: number + - name: body + in: body + schema: + title: Update a List request + type: object + properties: + name: + type: string + description: 'The new name for your list. ' + required: + - name responses: - '204': + '200': description: '' schema: - type: 'null' - '403': + type: object + properties: {} + '400': description: |- - "": "This campaign is already In Progress." - "": "This campaign is already Sent." - "": "This campaign is already Paused." - "": "This campaign is already Canceled." + "name" : "Returned if list name is a duplicate of existing list or segment" + "name" : "Returned if list name is invalid or not provided" + "list_id" : "Returned if list_id is not valid" + "" : "Returned if request body is invalid JSON" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: This campaign is already In Progress. - - field: null - message: This campaign is already Sent. - - field: null - message: This campaign is already Paused. - - field: null - message: This campaign is already Canceled. + - message: invalid id '404': - description: '"": "not found"' + description: '"list_id" : "Returned if list_id does not exist"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: not found - parameters: - - type: string - name: campaign_id - in: query + - message: List ID does not exist + summary: '' + security: + - Authorization: [] + get: + description: "Get a single list. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." + operationId: Get a single list. consumes: - application/json produces: - application/json - operationId: Unschedule a Scheduled Campaign - summary: |- - A successful unschedule will return a 204. - If the specified campaign is in the process of being sent, the only option is - description: |- - A successful unschedule will return a 204. - If the specified campaign is in the process of being sent, the only option is to cancel (a different method). - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - patch: + parameters: + - name: list_id + in: query + description: The ID of the list to retrieve. + type: number responses: '200': description: '' schema: - title: Update a Scheduled Campaign response - type: object - properties: - id: - type: integer - description: The campaign ID - send_at: - type: integer - description: The unix timestamp to send the campaign. - status: - type: string - description: The status of the schedule. - required: - - id - - send_at - - status + $ref: '#/definitions/contactdb_list' + examples: + application/json: + id: 1 + name: listname + recipient_count: 0 '400': - description: |- - "": "The JSON you have submitted cannot be parsed." - "send_at": "Please choose a future time for sending your campaign." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + description: '"list_id" : "Returned if list_id is not valid"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: send_at - message: Please choose a future time for sending your campaign. - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing' - '403': - description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' + - message: invalid id + '401': + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: send_at - message: You cannot update the send_at value of non-scheduled campaign. + - field: null + message: authorization required '404': - description: '"": "not found"' + description: '"list_id" : "Returned if list_id does not exist"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: not found - parameters: - - type: string - name: send_at - in: formData - required: true - description: '' + message: List ID does not exist + summary: '' + security: + - Authorization: [] + /contactdb/custom_fields: + parameters: [] + get: + description: "Get all custom fields. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." + operationId: List All Custom Fields consumes: - application/json produces: - application/json - operationId: Update a Scheduled Campaign - summary: Changes the send_at time for the specified campaign. - description: |- - Changes the send_at time for the specified campaign. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - get: + parameters: [] responses: '200': description: '' schema: - title: View Scheduled Time of a Campaign response + title: List All Custom Fields response type: object properties: - send_at: - type: integer - format: int64 + custom_fields: + type: array + items: + $ref: '#/definitions/contactdb_custom_field_with_id' required: - - send_at + - custom_fields examples: application/json: - send_at: 1490778528 - '404': - description: '"": "not found"' + lists: + - id: 1 + name: the jones + recipient_count: 1 + '401': + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: not found - parameters: [] + message: authorization required + summary: '' + security: + - Authorization: [] + post: + description: |- + Create a custom field. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Create a Custom Field consumes: - application/json produces: - application/json - operationId: View Scheduled Time of a Campaign - summary: '' - description: "View the time that this campaign is scheduled to be sent. \n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)" - security: - - {} - post: + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + type: + type: string responses: - '200': + '201': description: '' schema: - title: Schedule a Campaign response type: object properties: id: type: integer - description: The campaign ID. - send_at: - type: integer - description: The date time you scheduled your campaign to be sent. - status: + name: + type: string + type: type: string - description: The status of your campaign. - enum: - - Scheduled - required: - - id - - send_at - - status examples: application/json: - id: 1234 - send_at: 1489771528 - status: Scheduled + id: 1 + name: pet + type: text '400': description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "send_at": "Please choose a future time for sending your campaign." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "The JSON you have submitted cannot be parsed." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' + "" : "Returned if request body is invalid JSON" + "type" : "Returned if custom field type is invalid or not provided" + "name" : "Returned if custom field name is not provided" examples: application/json: errors: - - field: subject - message: "subject can't be blank" - - field: sender_id - message: "sender_id can't be blank" - - field: plain_content - message: "plain_content can't be blank, please provide plain text or html content" - - field: list_id - message: You must select at least 1 segment or 1 list to send to. - - field: unsubscribe_tag - message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' - - field: suppression_group_id - message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' - '401': + message: Returned if request body is invalid JSON + - field: type + message: Returned if custom field type is invalid or not provided + - field: name + message: Returned if custom field name is not provided + summary: '' + security: + - Authorization: [] + '/contactdb/custom_fields/{custom_field_id}': + parameters: + - name: custom_field_id + in: path + required: true + type: string + delete: + description: |- + Delete a custom field by ID. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Delete a Custom Field + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '202': description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + message: Custom Field delete is processing. + '400': + description: '"id" : "Returned if custom_field_id is not valid"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: authorization required - '403': - description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' + - message: Custom field in use by one or more segment conditions + - message: Custom field ID does not exist + '401': + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH. + message: authorization required '404': - description: '"": "not found"' + description: '"custom_field_id" : "Returned if custom_field_id does not exist"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: not found - parameters: - - type: string - name: send_at - in: formData - required: true - description: The unix timestamp for the date and time you would like your campaign to be sent out. - consumes: - - application/json - produces: - - application/json - operationId: Schedule a Campaign + - message: Custom field ID does not exist summary: '' + security: + - Authorization: [] + get: description: |- - Send your campaign at a specific date and time. - - For more information: + Get a custom field by ID. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - '/asm/groups/{group_id}/suppressions/{email}': - parameters: [] - delete: - responses: - '204': - description: '' - schema: - type: 'null' - parameters: [] + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Get a Custom Field consumes: - application/json produces: - application/json - operationId: Delete a Suppression from a Group - summary: '' - description: 'Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.' - security: - - {} - /asm/groups: - parameters: [] - get: + parameters: + - name: custom_field_id + in: query + description: The ID of the custom field you would like to retrieve + required: true + type: number responses: '200': description: '' schema: - type: array - items: - type: object - properties: - id: - type: number - name: - type: - - string - - 'null' - description: - type: - - string - - 'null' - last_email_sent_at: - type: - - object - - 'null' - properties: {} - is_default: - type: boolean - unsubscribes: - type: number + $ref: '#/definitions/contactdb_custom_field_with_id' examples: application/json: - - id: 1234 - name: Unsubscribe Group - description: An Unsubscribe Group - last_email_sent_at: null - is_default: true - unsubscribes: 1234 - - id: 1234 - name: Unsubscribe Group - description: An Unsubscribe Group - last_email_sent_at: null - is_default: true - unsubscribes: 1234 - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Retrieve all suppression groups associated with the user. - summary: '' - description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. - - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. - security: - - {} - post: - responses: - '200': + id: 1 + name: pet + type: text + '400': description: '' schema: - type: object - properties: - id: - type: number - name: - type: string - description: - type: string - last_email_sent_at: - type: 'null' - is_default: - type: boolean + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - id: 1234 - name: A group name - description: A group description - last_email_sent_at: null - is_default: false - parameters: - - type: string - name: name - in: formData - required: true - description: '' - - type: string - name: description - in: formData - required: true - description: '' - - type: string - name: is_default - in: formData - required: true + errors: + - message: invalid id + '401': description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"custom_field_id" : "Returned if custom_field_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: Custom field ID does not exist + summary: '' + security: + - Authorization: [] + '/api_keys/{api_key_id}': + parameters: + - name: api_key_id + in: path + required: true + type: string + patch: + description: |- + **Update the name of an existing API Key** + + A JSON request body with a "name" property is required. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + ## URI Parameters + + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are updating.| + operationId: Update API keys consumes: - application/json produces: - application/json - operationId: Create a Group - summary: '' - description: |- - Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts. - - The **name** and **description** of the Group will be visible by recipients when they are managing their subscriptions. - security: - - {} - '/asm/groups/{group_id}/suppressions': - parameters: [] - get: + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The new name of the API Key. responses: '200': description: '' schema: - type: array - items: - type: string + $ref: '#/definitions/api_key_name_id' examples: application/json: - - example@example.com - - example2@example.com - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get suppressed addresses for a given group. - summary: '' - description: 'Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.' - security: - - {} - post: - responses: - '201': + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + '401': description: '' schema: - type: object - properties: - recipient_emails: - type: array - items: - type: string + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - recipient_emails: - - test1@example.com - - test2@example.com - parameters: - - type: string - name: recipient_emails - in: formData - description: '' + errors: + - field: null + message: authorization required + summary: |- + **Update the name of an existing API Key** + + A JSON request body with a "name" property is required. + + The API Keys featur + security: + - Authorization: [] + get: + description: |- + Retrieve a single api key. + If the API Key ID does not exist an HTTP 404 will be returned. + + ## URI Parameters + + | Param | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key for which you are requesting information.| + operationId: Get an existing API Key consumes: - application/json produces: - application/json - operationId: Add Suppressions to a Group - summary: '' - description: 'Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses.' - security: - - {} - '/templates/{template_id}': - parameters: [] - patch: - responses: - '200': - description: '' + parameters: + - name: body + in: body schema: type: object properties: - id: - type: string name: type: string - versions: + description: The name you will use to describe this API Key. + scopes: type: array - items: {} - examples: - application/json: - id: 733ba07f-ead1-41fc-933a-3976baa23716 - name: new_example_name - versions: [] - parameters: - - type: string - name: name - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Edit a template. - summary: '' - description: '' - security: - - {} - delete: - responses: - '204': - description: '' - schema: - type: object - properties: {} - parameters: [] - consumes: - - application/json - produces: [] - operationId: Delete a template. - summary: '' - description: '' - security: - - {} - get: - responses: {} - parameters: [] - consumes: - - application/json - produces: [] - operationId: Retrieve a single template. - summary: '' - description: '' - security: - - {} - '/contactdb/lists/{list_id}/recipients': - parameters: [] - get: + description: The individual permissions that you are giving to this API Key. + items: + type: string + required: + - name responses: '200': description: '' schema: type: object properties: - recipients: + result: type: array + _isOpen: true items: - $ref: '#/definitions/contactdb_recipient' + $ref: '#/definitions/api_key_name_id_scopes' examples: application/json: - recipients: - - created_at: 1433348344 - custom_fields: - - id: 6234 - name: age - type: number - value: null - - id: 6233 - name: country - type: text - value: null - - id: 6235 - name: fname - type: text - value: Example - - id: 6239 - name: lname - type: text - value: User - - id: 6240 - name: lname - type: text - value: null - email: example@example.com - first_name: Example - id: ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv== - last_clicked: 1438616117 - last_emailed: 1438613272 - last_name: User - last_opened: 1438616109 - updated_at: 1438616119 - '400': - description: |- - "list_id" : "Returned if list_id is not a valid integer" - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id + '401': + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: list_id - message: Returned if list_id is not a valid integer - - field: page - message: Returned if page is not a valid integer - - field: page - message: Returned if page is less than 1 - - field: page_size - message: Returned if page_size is not a valid integer - - field: page_size - message: Returned if page_size is less than 1 or greater than 1000 + - field: null + message: authorization required '404': - description: '"list_id" : "Returned if list_id does not exist"' + description: Unexpected error in API call. See HTTP response body for details. schema: type: object properties: {} examples: application/json: errors: - - field: list_id - message: Returned if list_id is invalid - parameters: - - type: integer - description: Page index of first recipient to return (must be a positive integer) - name: page - in: query - - type: integer - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - name: page_size - in: query - - type: number - description: The ID of the list whose recipients you are requesting. - name: list_id - in: query - required: true + - field: null + message: unable to find API Key + summary: |- + Retrieve a single api key. + If the API Key ID does not exist an HTTP 404 will be returned. + security: + - Authorization: [] + put: + description: | + A JSON request body with a "name" property is required. + Most provide the list of all the scopes an api key should have. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + operationId: 'Update the name & scopes of an API Key' consumes: - application/json produces: - application/json - operationId: List Recipients on a List - summary: '' - description: |- - List all the recipients currently on a specific list. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - post: + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + scopes: + type: array + items: + type: string responses: - '201': + '200': description: '' schema: - type: 'null' - '400': - description: |- - "list_id" : "Returned if list_id is not a valid integer" - "" : "Returned if no valid recipient ids were passed" - "" : "Returned if no recipients were added" - "" : "Returned if request body is invalid JSON" + $ref: '#/definitions/api_key_name_id_scopes' + examples: + application/json: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + scopes: + - user.profile.read + - user.profile.update + '400': + description: Unexpected error in API call. See HTTP response body for details. schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: list_id - message: list_id is invalid - - field: recipient_id - message: no valid recipients were provided - - field: null - message: no recipients were added - field: null - message: request body is invalid JSON + message: "expected JSON request body with 'name' property" '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + type: object + properties: {} '404': - description: '"list_id": "Returned if list_id does not exist"' + description: Unexpected error in API call. See HTTP response body for details. schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: list_id - message: list_id does not exist - - field: recipient_id - message: recipient_id does not exist - parameters: - - type: number - description: 'The list to add your recipients to. ' - name: list_id - in: query - required: true + - field: null + message: unable to find API Key to update + summary: |- + A JSON request body with a "name" property is required. + Most provide the list of all the scopes an api key should have. + security: + - Authorization: [] + delete: + description: |- + **Revoke an existing API Key** + + Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + ## URI Parameters + + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are deleting.| + operationId: Delete API keys consumes: - application/json produces: - application/json - operationId: Add Multiple Recipients to a List - summary: 'Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they ' - description: |- - Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - /mail_settings/forward_spam: - parameters: [] - get: + parameters: [] responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' + type: 'null' + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - email: '' - enabled: true - parameters: [] + errors: + - field: null + message: unable to find API Key + summary: |- + **Revoke an existing API Key** + + Authentications using this API Key will fail after this request is made, with some small + security: + - Authorization: [] + '/user/scheduled_sends/{batch_id}': + parameters: + - name: batch_id + in: path + required: true + type: string + patch: + description: |- + Update the status of a scheduled send. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: Update user scheduled send information consumes: - application/json produces: - application/json - operationId: Get forward spam mail settings - summary: '' - description: '' - security: - - {} - patch: + parameters: + - name: body + in: body + schema: + type: object + properties: + status: + type: string + description: The status you would like the scheduled send to have. + enum: + - cancel + - pause + required: + - status responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' + type: 'null' + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - email: '' - enabled: false - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Update forward spam mail settings - summary: '' - description: '' - security: - - {} - /ips/warmup: - parameters: [] - post: - responses: - '200': + errors: + - field: status + message: status must be either cancel or pause + '401': description: '' schema: - type: array - items: - type: object - properties: - ip: - type: string - start_date: - type: integer + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - - ip: 0.0.0.0 - start_date: 1409616000 - parameters: - - type: string - name: ip - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Add an IP to warmup. - summary: '' - description: '' - security: - - {} - get: - responses: {} - parameters: [] - consumes: - - application/json - produces: [] - operationId: Get all IPs that are currently warming up. - summary: '' - description: '' - security: - - {} - /ips/pools: - parameters: [] - post: - responses: - '200': - description: '' + errors: + - field: null + message: authorization required + '404': + description: '"" : "batch id not found"' schema: - type: object - properties: - name: - type: string + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - name: marketing - parameters: - - type: string - name: name - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Create an IP pool. - summary: '' - description: '' - security: - - {} - get: - responses: {} - parameters: [] - consumes: - - application/json - produces: [] - operationId: List all IP pools. - summary: '' - description: '' + errors: + - field: null + message: batch id not found + summary: Update the status of a scheduled send. security: - - {} - /stats: - parameters: [] - get: - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - date: - type: string - stats: - type: array - items: - type: object - properties: - metrics: - type: object - properties: - blocks: - type: number - bounce_drops: - type: number - bounces: - type: number - clicks: - type: number - deferred: - type: number - delivered: - type: number - invalid_emails: - type: number - opens: - type: number - processed: - type: number - requests: - type: number - spam_report_drops: - type: number - spam_reports: - type: number - unique_clicks: - type: number - unique_opens: - type: number - unsubscribe_drops: - type: number - unsubscribes: - type: number + - Authorization: [] + delete: + description: |- + Delete the cancellation/pause of a scheduled send. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: Delete a cancellation or pause of a scheduled send + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '204': + description: '' + schema: + type: 'null' + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - - date: '2015-11-03' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-04' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-05' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-06' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-07' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-08' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-09' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - parameters: - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query + errors: + - field: null + message: authorization required + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: batch id not found + summary: Delete the cancellation/pause of a scheduled send. + security: + - Authorization: [] + get: + description: |- + Get cancel/paused scheduled send information for a specific batch_id. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: Retrieve scheduled send consumes: - application/json produces: - application/json - operationId: Global Stats provide all of your user’s email statistics for a given date range. - summary: '' - description: Global Stats provide all of your user’s email statistics for a given date range. + parameters: [] + responses: + '200': + description: '' + schema: + type: array + title: Retrieve scheduled send response + items: + $ref: '#/definitions/user_scheduled_send_status' + examples: + application/json: + - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + status: cancel + - batch_id: IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg + status: pause + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: |- + Get cancel/paused scheduled send information. If {batch_id} is omitted, all of the user's scheduled send cancellations + a security: - - {} - /contactdb/recipients: + - Authorization: [] + /user/scheduled_sends: parameters: [] post: + description: |- + Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will + be returned. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: Cancel or pause a scheduled send + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + title: Cancel or pause a scheduled send request + type: object + properties: + batch_id: + type: string + description: The batch ID is the identifier that your scheduled mail sends share. + pattern: '^[a-zA-Z0-9]' + status: + type: string + default: pause + description: 'The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}' + enum: + - pause + - cancel + required: + - batch_id + - status responses: '201': description: '' schema: - $ref: '#/definitions/contactdb_recipient_response' - examples: - application/json: - error_count: 1 - error_indices: - - 2 - new_count: 2 - persisted_recipients: - - YUBh - - bWlsbGVyQG1pbGxlci50ZXN0 - updated_count: 0 - errors: - - message: Invalid email. - error_indices: - - 2 + $ref: '#/definitions/user_scheduled_send_status' '400': - description: '"" : "Returned if request body is not valid json"' + description: |- + "" : "max limit reached" + "batch_id" : "invalid batch id" + "batch_id" : "a status for this batch id exists, try PATCH to update the status" schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: {} examples: application/json: errors: - field: null - message: Request body is not valid json + message: max limit reached + - field: batch_id + message: invalid batch id + - field: batch_id + message: 'a status for this batch id exists, try PATCH to update the status' '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: {} examples: application/json: errors: - field: null message: authorization required - parameters: [] + summary: |- + Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will + be returned. + security: + - Authorization: [] + get: + description: |- + Get all cancel/paused scheduled send information. + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: Get all scheduled sends consumes: - application/json produces: - application/json - operationId: Add recipients - summary: '' - description: |- - Add a recipient to your contactdb. It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - get: + parameters: [] responses: '200': description: '' schema: - title: List Recipients response - type: object - properties: - recipients: - type: array - items: - type: object - required: - - recipients - '400': - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" + type: array + items: + $ref: '#/definitions/user_scheduled_send_status' + examples: + application/json: + - batch_id: YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg + status: cancel + - batch_id: UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2 + status: cancel '401': description: '' schema: @@ -4488,45 +3955,35 @@ paths: errors: - field: null message: authorization required - parameters: - - type: integer - description: Page index of first recipients to return (must be a positive integer) - name: page - in: query - - type: integer - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - name: page_size - in: query + summary: '' + security: + - Authorization: [] + '/subusers/{subuser_name}': + parameters: + - name: subuser_name + in: path + required: true + type: string + delete: + description: |- + This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: Delete a subuser consumes: - application/json produces: - application/json - operationId: "List Recipients [waiting on Bryan Adamson's response]" - summary: | - {% info %} - Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of - description: |- - Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of - the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - patch: + parameters: [] responses: - '201': + '204': description: '' schema: - $ref: '#/definitions/contactdb_recipient_response' - '400': - description: '"" : "Returned if request body is not valid json"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: Request body is not valid json + type: object + properties: {} '401': description: '' schema: @@ -4536,36 +3993,46 @@ paths: errors: - field: null message: authorization required - parameters: [] + summary: '' + security: + - Authorization: [] + patch: + description: |- + This endpoint allows you to enable or disable a subuser. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: Enable/disable a subuser consumes: - application/json produces: - application/json - operationId: Update Recipient - summary: Updates one or more recipients. The body is a list of recipient objects. - description: |- - Updates one or more recipients. The body is an array of recipient objects. - - It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - delete: + parameters: + - name: body + in: body + schema: + type: object + properties: + disabled: + type: boolean + description: 'Whether or not this subuser is disabled. True means disabled, False means enabled.' responses: - '200': + '204': description: '' + schema: + type: object + properties: {} '400': - description: |- - "" : "Returned if no recipients are deleted" - "" : "Returned if all of the provided recipient ids are invalid" - "" : "Returned if request body is not valid json" + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: No recipient ids provided + - message: invalid username + - message: no fields provided '401': description: '' schema: @@ -4575,360 +4042,377 @@ paths: errors: - field: null message: authorization required - parameters: [] + '500': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: unable to enable user + summary: '' + security: + - Authorization: [] + /ips/assigned: + parameters: [] + get: + description: Retrieve a list of your IP addresses. + operationId: List all assigned IPs consumes: - application/json produces: - application/json - operationId: Delete Recipient - summary: Deletes one or more recipients. The body is a list of recipient ids to delete. - description: |- - Deletes one or more recipients. The body is a list of recipient ids to delete. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - '/templates/{template_id}/versions/{version_id}': - parameters: [] - patch: + parameters: [] responses: '200': description: '' schema: - type: object - properties: - id: - type: string - description: The ID of the template version. - updated_at: - type: string - description: The date and time that the template version was last updated. - Transactional Template Version: - $ref: '#/definitions/transactional_templates::versions' - required: - - id - - updated_at + type: array + title: List all assigned IPs response + items: + type: object + properties: + ip: + type: string + pools: + type: array + items: + type: string + warmup: + type: boolean + start_date: + type: integer examples: application/json: - id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f - template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d - active: 1 - name: version 1 name - html_content: '<%body%>' - plain_content: '<%body%>' - subject: '<%subject%>' - updated_at: '2014-03-19 18:56:33' - parameters: - - type: string - name: active - in: formData - description: Indicates if the template version is active. - - type: string - name: name - in: formData - description: The name of the template version. - - type: string - name: html_content - in: formData - description: The HTML content of the template version. - - type: string - name: plain_content - in: formData - description: The text/plain content of the template version. - - type: string - name: subject - in: formData - description: The subject of the template version. + - ip: 167.89.21.3 + pools: + - new_test5 + warmup: true + start_date: 1409616000 + summary: See only assigned IPs. + security: + - Authorization: [] + /mail_settings/plain_content: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your current Plain Content mail settings.** + + The plain content setting will automatically convert any plain text emails that you send to HTML before sending. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve plain content mail settings consumes: - application/json produces: - application/json - operationId: Edit a transactional template version. - summary: '' - description: |- - **This endpoint allows you to edit a version of one of your transactional templates.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - security: - - {} - delete: + parameters: [] responses: - '204': + '200': description: '' schema: - type: 'null' - parameters: [] - consumes: - - application/json - produces: [] - operationId: Delete a transactional template version. + type: object + properties: + enabled: + type: boolean + description: Indicates if the Plain Content mail setting is enabled. + examples: + application/json: + enabled: false summary: '' + security: + - Authorization: [] + patch: description: |- - **This endpoint allows you to delete one of your transactional template versions.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + **This endpoint allows you to update your current Plain Content mail settings.** - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + The plain content setting will automatically convert any plain text emails that you send to HTML before sending. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - security: - - {} - get: + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update plain content mail settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: The new setting you would like to use for your Plain Content mail setting. responses: '200': description: '' schema: type: object properties: - id: - type: string - description: The ID of the template version. - updated_at: - type: string - description: The date and time that the template version was last updated. - Transactional Template Version: - $ref: '#/definitions/transactional_templates::versions' - required: - - id - - updated_at + enabled: + type: boolean + description: Indicates if your Plain Content mail setting is enabled. examples: application/json: - id: 5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f - template_id: d51480ca-ca3f-465c-bc3e-ceb71d73c38d - active: 1 - name: version 1 name - html_content: '<%body%>' - plain_content: '<%body%>' - subject: '<%subject%>' - updated_at: '2014-03-19 18:56:33' - parameters: [] + enabled: false + summary: '' + security: + - Authorization: [] + '/campaigns/{campaign_id}/schedules': + parameters: + - name: campaign_id + in: path + required: true + type: integer + get: + description: "View the time that this campaign is scheduled to be sent. \n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)" + operationId: View Scheduled Time of a Campaign consumes: - application/json produces: - application/json - operationId: Retrieve a specific transactional template version. - summary: '' - description: |- - **This endpoint allows you to retrieve a specific version of a template.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - security: - - {} - /contactdb/recipients/billable_count: - parameters: [] - get: + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_recipient_count' + title: View Scheduled Time of a Campaign response + type: object + properties: + send_at: + type: integer + format: int64 + required: + - send_at examples: application/json: - recipient_count: 1234 - '401': - description: '' + send_at: 1490778528 + '404': + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: authorization required - parameters: [] + message: not found + summary: '' + security: + - Authorization: [] + patch: + description: |- + Changes the send_at time for the specified campaign. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Update a Scheduled Campaign consumes: - application/json produces: - application/json - operationId: Get the count of billable recipients - summary: '' - description: |- - You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - '/contactdb/segments/{segment_id}': - parameters: [] - get: + parameters: + - name: body + in: body + schema: + title: Update a Scheduled Campaign request + type: object + properties: + send_at: + type: integer + format: int64 + required: + - send_at responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_segments' - examples: - application/json: - id: 1 - name: Last Name Miller - list_id: 4 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - recipient_count: 1 + title: Update a Scheduled Campaign response + type: object + properties: + id: + type: integer + description: The campaign ID + send_at: + type: integer + description: The unix timestamp to send the campaign. + status: + type: string + description: The status of the schedule. + required: + - id + - send_at + - status '400': - description: '"segment_id" : "Returned if segment_id is not valid"' + description: |- + "": "The JSON you have submitted cannot be parsed." + "send_at": "Please choose a future time for sending your campaign." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: if segment_id is not valid - '401': - description: '' + - field: send_at + message: Please choose a future time for sending your campaign. + - field: null + message: The JSON you have submitted cannot be parsed. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing' + '403': + description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: authorization required + - field: send_at + message: You cannot update the send_at value of non-scheduled campaign. '404': - description: '"segment_id" : "Returned if segment_id does not exist"' + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: segment_id not found - parameters: - - type: number - description: The ID of the segment you want to request. - name: segment_id - in: query - required: true + - field: null + message: not found + summary: Changes the send_at time for the specified campaign. + security: + - Authorization: [] + delete: + description: |- + A successful unschedule will return a 204. + If the specified campaign is in the process of being sent, the only option is to cancel (a different method). + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Unschedule a Scheduled Campaign consumes: - application/json produces: - application/json - operationId: Retrieve a Segment - summary: '' - description: |- - Get a single segment by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - delete: + parameters: [] responses: '204': description: '' schema: type: 'null' - '400': + '403': description: |- - "segment_id" : "Returned if segment_id is not valid" - "delete_contacts" : "Returned if delete_contacts is not a valid boolean" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: segment_id - message: Returned if segment_id is not valid - - field: delete_contacts - message: Returned if delete_contacts is not a valid boolean - '401': - description: '' + "": "This campaign is already In Progress." + "": "This campaign is already Sent." + "": "This campaign is already Paused." + "": "This campaign is already Canceled." schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: authorization required + message: This campaign is already In Progress. + - field: null + message: This campaign is already Sent. + - field: null + message: This campaign is already Paused. + - field: null + message: This campaign is already Canceled. '404': - description: '"segment_id" : "Returned if segment_id does not exist"' + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: segment_id - message: segment_id does not exist - parameters: - - type: boolean - description: True to delete all contacts matching the segment in addition to deleting the segment - name: delete_contacts - in: query + - field: null + message: not found + summary: |- + A successful unschedule will return a 204. + If the specified campaign is in the process of being sent, the only option is + security: + - Authorization: [] + post: + description: |- + Send your campaign at a specific date and time. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Schedule a Campaign consumes: - application/json produces: - application/json - operationId: Delete a Segment - summary: '' - description: |- - Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - patch: + parameters: + - name: body + in: body + schema: + title: Schedule a Campaign request + type: object + properties: + send_at: + type: integer + description: The unix timestamp for the date and time you would like your campaign to be sent out. + required: + - send_at responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/contactdb_segments' + title: Schedule a Campaign response + type: object + properties: + id: + type: integer + description: The campaign ID. + send_at: + type: integer + description: The date time you scheduled your campaign to be sent. + status: + type: string + description: The status of your campaign. + enum: + - Scheduled + required: + - id + - send_at + - status examples: application/json: - id: 5 - name: The Millers - list_id: 5 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - recipient_count: 1 + id: 1234 + send_at: 1489771528 + status: Scheduled '400': - description: '' + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "send_at": "Please choose a future time for sending your campaign." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "The JSON you have submitted cannot be parsed." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: request body is not valid json - - message: invalid value is passed into one of the request body parameters - - segment_id: segment_id - message: segment id is not valid - - field: field - message: field and set value is not passed into the request body - - field: value - message: value and set value is not passed into the request body - - field: operator - message: operator and set value is not passed into the request body - - field: and_or - message: and_or is not set on more than one condition and less than all conditions - - field: and_or - message: and_or is set on all conditions - - field: and_or - message: and_or is set on the only condition passed - - field: and_or - message: and_or and set value is not passed into the request body + - field: subject + message: "subject can't be blank" + - field: sender_id + message: "sender_id can't be blank" + - field: plain_content + message: "plain_content can't be blank, please provide plain text or html content" - field: list_id - message: the list_id is not valid - - field: name - message: the name is not valid + message: You must select at least 1 segment or 1 list to send to. + - field: unsubscribe_tag + message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' + - field: suppression_group_id + message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' '401': description: '' schema: @@ -4938,153 +4422,41 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - description: The ID of the segment you are updating. - name: segment_id - in: query - - type: string - name: name - in: formData - required: true - description: '' - - type: string - name: list_id - in: formData - required: false - description: The list ID you would like this segment to be built from. - - type: string - name: conditions - in: formData - required: false - description: The conditions by which this segment should be created. - consumes: - - application/json - produces: - - application/json - operationId: Update a segment - summary: '' - description: |- - Update a segment. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - /partner_settings/new_relic: - parameters: [] - get: - responses: - '200': - description: '' + '403': + description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' schema: - $ref: '#/definitions/partner_settings_new_relic' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - enable_subuser_statistics: false - enabled: true - license_key: '' - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get new relic partner settings - summary: '' - description: '' - security: - - {} - patch: - responses: - '200': - description: '' + errors: + - field: null + message: You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH. + '404': + description: '"": "not found"' schema: - $ref: '#/definitions/partner_settings_new_relic' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - enable_subuser_statistics: true - enabled: true - license_key: '' - parameters: - - type: string - name: license_key - in: formData - description: '' - - type: string - name: enabled - in: formData - description: '' - - type: string - name: enable_subuser_statistics - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Update new relic partner settings + errors: + - field: null + message: not found summary: '' - description: '' security: - - {} - /mail_settings/spam_check: - parameters: [] + - Authorization: [] + '/suppression/bounces/{email}': + parameters: + - name: email + in: path + required: true + type: string get: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_spam_check' - examples: - application/json: - enabled: false - max_score: 6 - url: 'http://example.com' - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get spam check mail settings - summary: '' description: '' - security: - - {} - patch: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_spam_check' - examples: - application/json: - enabled: false - max_score: 6 - url: 'http://example.com' - parameters: - - type: string - name: enabled - in: formData - description: '' - - type: string - name: url - in: formData - description: '' - - type: string - name: max_score - in: formData - description: '' + operationId: Get a Bounce consumes: - application/json produces: - application/json - operationId: Update spam check mail settings - summary: '' - description: '' - security: - - {} - /clients/stats: - parameters: [] - get: + parameters: [] responses: '200': description: '' @@ -5093,221 +4465,97 @@ paths: items: type: object properties: - date: + created: + type: integer + email: + type: string + reason: + type: string + status: type: string - stats: - type: array - items: - type: object - properties: - metrics: - type: object - properties: - opens: - type: integer - unique_opens: - type: integer - name: - type: string - type: - type: string examples: application/json: - - date: '2014-10-01' - stats: - - metrics: - opens: 1 - unique_opens: 1 - name: Gmail - type: client - - date: '2014-10-02' - stats: - - metrics: - opens: 0 - unique_opens: 0 - name: Gmail - type: client - parameters: - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query - - type: string - name: aggregated_by - in: query - consumes: - - application/json - produces: - - application/json - operationId: Retrieve stats by client type - summary: Gets email statistics by client type. - description: Gets email statistics by client type. + - created: 1443651125 + email: bounce1@test.com + reason: "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp " + status: 5.1.1 + summary: '' security: - - {} - '/ips/warmup/{ip_address}': - parameters: [] + - Authorization: [] delete: - responses: - '204': - description: '' - schema: - type: object - properties: {} - parameters: [] + description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)" + operationId: Delete a bounce consumes: - application/json - produces: [] - operationId: Remove an IP from warmup. - summary: '' - description: '' - security: - - {} - get: - responses: {} - parameters: [] - consumes: + produces: - application/json - produces: [] - operationId: Get warmup status for a particular IP. - summary: '' - description: '' - security: - - {} - '/ips/pools/{pool_name}': - parameters: [] - delete: + parameters: + - name: email_address + in: query + description: The email address you would like to remove from the bounce list. + required: true + type: string + format: email responses: '204': description: '' schema: type: object properties: {} - parameters: [] - consumes: - - application/json - produces: [] - operationId: Delete an IP pool. - summary: '' - description: '' - security: - - {} - put: - responses: {} - parameters: [] - consumes: - - application/json - produces: [] - operationId: Update an IP pool’s name. - summary: '' - description: '' - security: - - {} - get: - responses: - '200': + '401': description: '' schema: - type: object - properties: - pool_name: - type: string - ips: - type: array - items: - type: string - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: List the IPs in a specified pool. + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required summary: '' - description: '' security: - - {} - '/asm/suppressions/{email}': + - Authorization: [] + /mail_settings/template: parameters: [] - delete: - responses: - '200': - description: '' - parameters: [] + get: + description: "**This endpoint allows you to retrieve your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html)." + operationId: Retrieve legacy template mail settings consumes: - application/json produces: - application/json - operationId: Delete a Global Suppression - summary: '' - description: '' - security: - - {} - get: + parameters: [] responses: '200': description: '' schema: - title: Retrieve a Global Suppression response - type: object - properties: - recipient_email: - type: string - required: - - recipient_email - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Retrieve a Global Suppression + $ref: '#/definitions/mail_settings_template' + examples: + application/json: + enabled: false + html_content: | +

<% body %>Example

summary: '' - description: '' security: - - {} - /tracking_settings/subscription: - parameters: [] + - Authorization: [] patch: - responses: - '200': - description: '' - schema: - type: object - parameters: - - type: string - name: enabled - in: formData - description: '' - - type: string - name: landing - in: formData - description: '' - - type: string - name: url - in: formData - description: '' - - type: string - name: replace - in: formData - description: '' - - type: string - name: html_content - in: formData - description: '' - - type: string - name: plain_content - in: formData - description: '' + description: "**This endpoint allows you to update your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). \n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages.\n\nMail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html)." + operationId: Update template mail settings consumes: - application/json produces: - application/json - operationId: Update Subscription Tracking Settings - summary: '' - description: '' - security: - - {} - get: + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if you want to enable the legacy email template mail setting. + html_content: + type: string + description: The new HTML content for your legacy email template. responses: '200': description: '' @@ -5318,887 +4566,725 @@ paths: type: boolean html_content: type: string - landing: - type: string - plain_content: - type: string - replace: - type: string - url: - type: string examples: application/json: - enabled: true + enabled: false html_content: | -

Something something unsubscribe <% %> something something

- landing: | -

subscribehere

- plain_content: 'Something something unsubscribe <% %> something something' - replace: thetag - url: '' - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get Subscription Tracking Settings - summary: '' - description: '' - security: - - {} - '/ips/pools/{pool_name}/ips/{ip}': - parameters: [] - delete: - responses: {} - parameters: [] - consumes: - - application/json - produces: [] - operationId: Remove an IP address from a pool. +

<% body %>Example

summary: '' - description: '' security: - - {} - /whitelabel/links/default: + - Authorization: [] + /mail_settings/address_whitelist: parameters: [] get: - responses: - '200': - description: '' - schema: - type: object - properties: - id: - type: integer - domain: - type: string - subdomain: - type: string - username: - type: string - user_id: - type: integer - default: - type: boolean - valid: - type: boolean - legacy: - type: boolean - dns: - type: object - properties: - domain_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - owner_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - examples: - application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - parameters: - - type: string - name: domain - in: query + description: |- + **This endpoint allows you to retrieve your current email address whitelist settings.** + + The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve address whitelist mail settings consumes: - application/json produces: - application/json - operationId: Default Link - summary: 'Default link is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, th' - description: |- - Default link is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: -
    -
  • Validated link whitelabels marked as "default"
    • -
  • Legacy link whitelabels (migrated from the whitelabel wizard)
    • -
  • Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net)
    • -
- security: - - {} - '/contactdb/lists/{list_id}/recipients/{recipient_id}': - parameters: [] - post: + parameters: [] responses: - '201': - description: '' - schema: - type: 'null' - '400': - description: |- - "list_id" : "Returned if list_id is invalid" - "recipient_id" : "Returned if recipient_id is invalid" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: Returned if recipient_id is invalid - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_address_whitelabel' examples: application/json: - errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist - parameters: - - type: number - description: The ID of the list to add the recipient to. - name: list_id - in: query - - type: string - description: The recipient you are adding to the list indicated. - name: recipient_id - in: query + enabled: false + list: + - example.com + summary: '' + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update your current email address whitelist settings.** + + The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update address whitelist mail settings consumes: - application/json produces: - application/json - operationId: Add a Single Recipient to a List - summary: '' - description: |- - Add a recipient to a list. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - delete: + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if your email address whitelist is enabled. + list: + type: array + description: 'Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.' + items: + type: string responses: - '204': + '200': description: '' schema: - type: 'null' - '400': - description: |- - "list_id" : "Returned if list_id is not valid" - "recipient_id" : "Returned if recipient_id is not valid" - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_address_whitelabel' examples: application/json: - errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: no valid recipients were provided - '401': + enabled: true + list: + - email1@example.com + summary: '' + security: + - Authorization: [] + /mail_settings/footer: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your current Footer mail settings.** + + The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve footer mail settings + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_footer' examples: application/json: - errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist - parameters: - - type: number - description: The ID of the list you are taking this recipient away from. - name: list_id - in: query - required: true - - type: number - description: The ID of the recipient to take off the list. - name: recipient_id - in: query - required: true + enabled: true + html_content: Example HTML content + plain_content: Example plain content + summary: '' + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update your current Footer mail settings.** + + The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update footer mail settings consumes: - application/json produces: - application/json - operationId: Delete a Single Recipient from a Single List - summary: '' - description: |- - Delete a single recipient from a list. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - /ips: - parameters: [] - get: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/mail_settings_footer' responses: '200': description: '' schema: - type: array - items: - type: object - properties: - ip: - type: string - subusers: - type: array - items: - type: string - rdns: - type: string - pools: - type: array - items: - type: object - properties: {} - warmup: - type: boolean - start_date: - type: - - number - - 'null' - whitelabeled: - type: boolean + $ref: '#/definitions/mail_settings_footer' examples: application/json: - - ip: 127.0.0.1 - subusers: - - example_subuser1 - - example_subuser2 - rdns: o1.em.example.com - pools: [] - warmup: true - start_date: 1250337600 - whitelabeled: true - - ip: 127.0.0.1 - subusers: [] - pools: [] - warmup: false - start_date: null - whitelabeled: false - parameters: - - type: string - description: The IP address to get - name: ip - in: query - - type: string - description: Should we exclude whitelabels? - name: exclude_whitelabels - in: query - - type: string - description: The subuser you are requesting for. - name: subuser - in: query - - type: string - default: 10 - description: The number of IPs you want returned at the same time. - name: limit - in: query - - type: string - default: 0 - description: The offset for the number of IPs that you are requesting. - name: offset - in: query + enabled: true + html_content: Example HTML content + plain_content: Example plain content + summary: '' + security: + - Authorization: [] + '/asm/suppressions/global/{email}': + parameters: + - name: email + in: path + required: true + type: string + get: + description: '' + operationId: Retrieve a Global Suppression consumes: - application/json produces: - application/json - operationId: List all IPs - summary: |- - See a list of all assigned and unassigned IPs. - Response includes warm up status, pools, assigned subusers, and whitelabe - description: |- - See a list of all assigned and unassigned IPs. - Response includes warm up status, pools, assigned subusers, and whitelabel info. - The start_date field corresponds to when warmup started for that IP. - security: - - {} - '/whitelabel/domains/{id}/validate': - parameters: [] - post: + parameters: [] responses: '200': description: '' schema: + title: Retrieve a Global Suppression response type: object properties: - id: - type: integer - description: The ID of the domain whitelabel. - valid: - type: boolean - description: Indicates if this is a valid whitelabel. - validation_resuts: - type: object - description: 'The individual DNS records that are checked when validating, including the reason for any invalid DNS records.' - properties: - mail_cname: - type: object - description: The CNAME record for the domain whitelabel. - properties: - valid: - type: boolean - description: Indicates if this DNS record is valid. - reason: - type: string - description: The reason this record is invalid. - dkim1: - type: object - description: A DNS record for this domain whitelabel. - properties: - valid: - type: boolean - description: Indicates if the DNS record is valid. - reason: - type: 'null' - dkim2: - type: object - description: A DNS record for this whitelabel. - properties: - valid: - type: boolean - description: Indicates if the DNS record is valid. - reason: - type: 'null' - spf: - type: object - description: The SPF record for the whitelabel. - properties: - valid: - type: boolean - description: Indicates if the SPF record is valid. - reason: - type: 'null' + recipient_email: + type: string + required: + - recipient_email + summary: '' + security: + - Authorization: [] + delete: + description: '' + operationId: Delete a Global Suppression + consumes: + - application/json + produces: [] + parameters: [] + responses: + '204': + description: '' + summary: '' + security: + - Authorization: [] + /partner_settings/new_relic: + parameters: [] + patch: + description: |- + **This endpoint allows you to update or change your New Relic partner settings.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). + operationId: Updates New Relic partner settings. + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + license_key: + type: string + description: The license key for your New Relic account. + enabled: + type: boolean + description: Indicates if this partner setting is enabled. + enable_subuser_statistics: + type: boolean + description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. + responses: + '200': + description: '' + schema: + $ref: '#/definitions/partner_settings_new_relic' examples: application/json: - id: 1 - valid: true - validation_resuts: - mail_cname: - valid: false - reason: 'Expected your MX record to be "mx.sendgrid.net" but found "example.com".' - dkim1: - valid: true - reason: null - dkim2: - valid: true - reason: null - spf: - valid: true - reason: null - '400': - description: Unexpected error in API call. See HTTP response body for details. + enable_subuser_statistics: true + enabled: true + license_key: '' + summary: '' + security: + - Authorization: [] + get: + description: |- + **This endpoint allows you to retrieve your current New Relic partner settings.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). + operationId: Returns all New Relic partner settings. + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': + description: '' schema: - type: object - properties: {} - '500': + $ref: '#/definitions/partner_settings_new_relic' + examples: + application/json: + enable_subuser_statistics: false + enabled: true + license_key: '' + summary: '' + security: + - Authorization: [] + /partner_settings: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve a list of all partner settings that you can enable.** + + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + operationId: Returns a list of all partner settings. + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of settings to return per page. + type: integer + - name: offset + in: query + description: The paging offset. + type: integer + responses: + '200': description: '' schema: type: object properties: - errors: + result: type: array items: type: object properties: - message: + title: type: string - description: A message explaining the reason for the error. + description: The title of the partner. + enabled: + type: boolean + description: Indicates if this partner setting has been enabled. + name: + type: string + description: The name of the partner setting. + description: + type: string + description: A description of this partner setting. required: - - message + - title + - enabled + - name + - description examples: application/json: - errors: - - message: internal error getting TXT - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Validate a domain whitelabel. + result: + - title: Partner title + enabled: true + name: partner_name + description: A description of a partner. summary: '' + security: + - Authorization: [] + /mail_settings/forward_spam: + parameters: [] + patch: description: |- - **This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to update your current Forward Spam mail settings.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer |ID of the domain whitelabel to validate. | - security: - - {} - '/contactdb/recipients/{recipient_id}': - parameters: [] - get: + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update forward spam mail settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/mail_settings_forward_spam' responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_recipient' - '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_forward_spam' examples: application/json: - errors: - - field: null - message: authorization required - '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' - parameters: - - type: string - description: The ID of the created recipient. - name: recipient_id - in: query + email: '' + enabled: false + summary: '' + security: + - Authorization: [] + get: + description: |- + **This endpoint allows you to retrieve your current Forward Spam mail settings.** + + Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve forward spam mail settings consumes: - application/json produces: - application/json - operationId: Retrieve a single recipient - summary: '' - description: |- - Retrieve a single recipient by ID from your contact database. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - delete: + parameters: [] responses: - '204': + '200': description: '' schema: - type: object - properties: {} - '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_forward_spam' examples: application/json: - errors: - - field: null - message: recipient not found - '401': - description: '' + email: '' + enabled: true + summary: '' + security: + - Authorization: [] + /mail_settings/forward_bounce: + parameters: [] + patch: + description: |- + **This endpoint allows you to update your current bounce forwarding mail settings.** + + Activating this setting allows you to specify an email address to which bounce reports are forwarded. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update forward bounce mail settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' + $ref: '#/definitions/mail_settings_forward_bounce' + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_forward_bounce' examples: application/json: - errors: - - field: null - message: recipient_id is not valid - parameters: - - type: string - description: The ID of the recipient to be deleted. - name: recipient_id - in: query - required: true + email: '' + enabled: true + summary: '' + security: + - Authorization: [] + get: + description: |- + **This endpoint allows you to retrieve your current bounce forwarding mail settings.** + + Activating this setting allows you to specify an email address to which bounce reports are forwarded. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve forward bounce mail settings consumes: - application/json produces: - application/json - operationId: Delete a Recipient - summary: '' - description: |- - Delete a single recipient from your contact database, by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - '/campaigns/{campaign_id}/schedules/test': - parameters: [] - post: + parameters: [] responses: '200': description: '' schema: - title: Send a Test Campaign request - type: object - properties: - to: - type: string - required: - - to - '400': - description: |- - "": "The JSON you have submitted cannot be parsed." - "to": "Please provide an email address to which the test should be sent." - "to": "You can only send tests to 10 addresses at a time." - "subject": "Please add a subject to your campaign before sending a test." - "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." - "sender_id": "Please assign a sender identity to your campaign before sending a test." - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_forward_bounce' examples: application/json: - errors: - - field: send_at - message: Please choose a future time for sending your campaign. - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' - '404': - description: '"": "not found"' + enabled: false + email: null + summary: '' + security: + - Authorization: [] + /categories: + parameters: [] + get: + description: '' + operationId: Get categories + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + type: integer + - name: sort_by + in: query + type: string + - name: order + in: query + type: string + - name: category + in: query + type: string + - name: offset + in: query + type: integer + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + type: object + properties: + category: + type: string examples: application/json: - errors: - - field: null - message: not found - parameters: - - type: string - name: campaign_id - in: query - - type: string - name: to - in: formData - required: true - description: The email address that should receive the test campaign. + - category: category 1 + - category: category 2 + summary: '' + security: + - Authorization: [] + /user/account: + parameters: [] + get: + description: "Your user's account information includes the user's account type and reputation." + operationId: "Get a user's account information." consumes: - application/json produces: - application/json - operationId: Send a Test Campaign - summary: 'To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"]' - description: |- - To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - '/campaigns/{campaign_id}': - parameters: [] - patch: + parameters: [] responses: '200': description: '' schema: - title: Update a Campaign response + title: GET User Account response type: object properties: - id: - type: integer - format: int64 - title: - type: string - subject: - type: string - sender_id: - type: integer - format: int64 - list_ids: - type: array - items: - type: integer - format: int64 - segment_ids: - type: array - items: - type: integer - format: int64 - categories: - type: array - items: - type: string - suppression_group_id: - type: integer - format: int64 - custom_unsubscribe_url: - type: string - ip_pool: - type: string - html_content: - type: string - plain_content: - type: string - status: + type: type: string + description: The type of account for this user. + enum: + - free + - paid + reputation: + type: number + description: The sender reputation for this user. required: - - id - - title - - subject - - sender_id - - list_ids - - segment_ids - - categories - - suppression_group_id - - custom_unsubscribe_url - - ip_pool - - html_content - - plain_content - - status - examples: - application/json: - id: 986724 - title: May Newsletter - subject: 'New Products for Summer!' - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - summer line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content: '

Check out our summer line!

' - plain_content: 'Check out our summer line!' - status: Draft - '400': - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." + - type + - reputation examples: application/json: - errors: - - field: title - message: "title can't be blank" - - field: title - message: title is too long (maximum is 100 characters) - - field: categories - message: categories exceeds 10 category limit - - field: html_content - message: html_content exceeds the 1MB limit - - field: plain_content - message: plain_content exceeds the 1MB limit - - field: sender_id - message: sender_id does not exist - - field: sender_id - message: sender_id is not a verified sender identity - - field: list_ids - message: list_ids do not all exist - - field: segment_ids - message: segment_ids do not all exist - - field: ip_pool - message: The ip pool you provided is invalid - - field: suppression_group_id - message: suppression_group_id does not exist - - field: unsubscribes - message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - - field: null - message: The JSON you have submitted cannot be parsed. - '401': + reputation: 100 + type: paid + summary: '' + security: + - Authorization: [] + /whitelabel/ips: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve all of the IP whitelabels that have been createdy by this account.** + + You may include a search key by using the "ip" parameter. This enables you to perform a prefix search for a given IP segment (e.g. "192."). + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: Retrieve all IP whitelabels + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of results to retrieve. + type: integer + - name: offset + in: query + description: The point in the list of results to begin retrieving IPs from. + type: integer + - name: ip + in: query + description: The IP segment that you would like to use in a prefix search. + type: string + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '"": "You may only update a campaign when it is in draft mode."' - schema: - type: object - properties: {} - examples: - application/json: - errors: - - field: null - message: You may only update a campaign when it is in draft mode. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + $ref: '#/definitions/ip_whitelabel' examples: application/json: - errors: - - field: null - message: not found - parameters: - - type: string - name: campaign_id - in: query - - type: string - name: title - in: formData - required: true - description: The title of the campaign. - - type: string - name: subject - in: formData - required: true - description: The subject line for your campaign. - - type: string - name: categories - in: formData - required: true - description: The categories you want to tag on this campaign. - - type: string - name: html_content - in: formData - required: true - description: The HTML content of this campaign. - - type: string - name: plain_content - in: formData - required: true - description: The plain content of this campaign. + - id: 1 + ip: 192.168.1.1 + rdns: o1.email.example.com + users: + - username: john@example.com + user_id: 7 + - username: jane@example.com + user_id: 8 + subdomain: email + domain: example.com + valid: true + legacy: false + a_record: + valid: true + type: a + host: o1.email.example.com + data: 192.168.1.1 + - id: 2 + ip: 192.168.1.2 + rdns: o2.email.example.com + users: + - username: john@example.com + user_id: 7 + - username: jane@example2.com + user_id: 9 + subdomain: email + domain: example.com + valid: true + legacy: false + a_record: + valid: true + type: a + host: o2.email.example.com + data: 192.168.1.2 + summary: '' + security: + - Authorization: [] + post: + description: |- + **This endpoint allows you to create an IP whitelabel.** + + When creating an IP whitelable, you should use the same subdomain that you used when you created a domain whitelabel. + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: Create an IP whitelabel consumes: - application/json produces: - application/json - operationId: Update a Campaign + parameters: + - name: body + in: body + schema: + type: object + properties: + ip: + type: string + description: The IP address that you want to whitelabel. + subdomain: + type: string + description: The subdomain that will be used to send emails from the IP. Should be the same as the subdomain used for your domain whitelabel. + domain: + type: string + description: 'The root, or sending, domain that will be used to send message from the IP.' + required: + - ip + - subdomain + - domain + responses: + '201': + description: '' + schema: + $ref: '#/definitions/ip_whitelabel' + examples: + application/json: + id: 123 + ip: 192.168.1.2 + rdns: o1.email.example.com + users: [] + subdomain: email + domain: example.com + valid: true + legacy: false + a_record: + valid: true + type: a + host: o1.email.example.com + data: 192.168.1.2 summary: '' - description: |- - Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) security: - - {} + - Authorization: [] + '/contactdb/segments/{segment_id}/recipients': + parameters: + - name: segment_id + in: path + required: true + type: integer get: + description: |- + List all of the recipients in a segment. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: List Recipients On a Segment + consumes: + - application/json + produces: + - application/json + parameters: + - name: page + in: query + type: integer + - name: page_size + in: query + type: integer responses: '200': description: '' schema: - $ref: '#/definitions/campaign_response' + title: List Recipients On a Segment response + type: object + properties: + recipients: + type: array + items: + $ref: '#/definitions/contactdb_recipient' + required: + - recipients examples: application/json: - id: 986724 - title: March Newsletter - subject: 'New Products for Spring!' - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content: '

Check out our spring line!

' - plain_content: 'Check out our spring line!' - status: Draft + recipients: + - created_at: 1422313607 + email: jones@example.com + first_name: null + id: YUBh + last_clicked: null + last_emailed: null + last_name: Jones + last_opened: null + updated_at: 1422313790 + custom_fields: + - id: 23 + name: pet + value: Indiana + type: text + '400': + description: |- + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" '401': description: '' schema: - type: object - properties: {} + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null message: authorization required '404': - description: '"": "not found"' - examples: - application/json: - errors: - - field: null - message: not found - parameters: - - type: number - description: The id of the campaign to retrieve. - name: campaign_id - in: query - required: true + description: |- + "segment_id" : "Returned if segment_id is not valid" + "segment_id" : "Returned if segment_id does not exist" + summary: '' + security: + - Authorization: [] + /suppression/bounces: + parameters: [] + delete: + description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes." + operationId: Delete bounces consumes: - application/json produces: - application/json - operationId: Get a single campaign - summary: '' - description: |- - This is a place for notes and extra information about this endpoint. It is written - in Markdown - more info in the [documentation](/docs/designer#markdown). - - There are several special markdown helpers that automatically build tables - and html off of your endpoint definition. You can find some examples in this content. - - Click the "Open Editor" button above to start editing this content. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - delete: + parameters: + - name: body + in: body + schema: + type: object + properties: + delete_all: + type: boolean + description: 'This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter.' + emails: + type: array + description: Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter. + items: + type: string responses: '204': description: '' @@ -6207,55 +5293,63 @@ paths: '401': description: '' schema: - type: object - properties: {} + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null message: authorization required - '404': - description: '"": "not found"' - parameters: - - type: string - description: The ID of the campaign to delete. - name: campaign_id - in: query - required: true + summary: '' + security: + - Authorization: [] + get: + description: "Bounces are messages that are returned to the server that sent it. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)" + operationId: List all bounces consumes: - application/json produces: - application/json - operationId: Delete a Campaign - summary: '' - description: |- - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - '/mail/batch/{batch_id}': - parameters: [] - get: + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). + type: number + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). + type: number + - name: Allow + in: header + description: '' + type: string responses: '200': description: '' schema: - $ref: '#/definitions/mail_batch_id' - examples: - application/json: - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + type: object + properties: + created: + type: number + email: + type: string + reason: + type: string + status: + type: string examples: application/json: - errors: - - field: null - message: invalid batch id + - created: 1250337600 + email: example@example.com + reason: "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp " + status: 5.1.1 + - created: 1250337600 + email: example@example.com + reason: '550 5.1.1 : Recipient address rejected: User unknown in virtual alias table ' + status: 5.1.1 '401': - description: Unexpected error in API call. See HTTP response body for details. + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: @@ -6263,42 +5357,56 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - description: 'The ID you can use to associate multiple scheduled sends together, in case you might want to cancel or pause those sends.' - pattern: '^[A-Za-z0-9]' - name: batch_id - in: query - required: true + summary: '' + security: + - Authorization: [] + /subusers: + parameters: [] + get: + description: |- + This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: List all Subusers consumes: - application/json produces: - application/json - operationId: Validate batch ID - summary: Validate whether or not a batch id is valid - description: "Validate whether or not a batch id is valid.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" - security: - - {} - /mail/batch: - parameters: [] - post: + parameters: + - name: username + in: query + description: The username of this subuser. + type: string + - name: limit + in: query + description: The number of results you would like to get in each request. + type: number + - name: offset + in: query + description: The number of subusers to skip. + type: number responses: - '201': - description: '' - schema: - title: Generate Batch ID response - type: object - properties: - batch_id: - type: string - pattern: "^[a-zA-Z0-9\\-\\_]" - required: - - batch_id + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/subuser' examples: application/json: - batch_id: YOUR_BATCH_ID + - disabled: false + email: example@example.com + id: 1234 + username: example_subuser + - disabled: false + email: example2@example.com + id: 1234 + username: example_subuser2 '401': - description: '' + description: Unexpected error in API call. See HTTP response body for details. schema: $ref: '#/definitions/global:ErrorResponse' examples: @@ -6306,78 +5414,72 @@ paths: errors: - field: null message: authorization required - parameters: [] + summary: '' + security: + - Authorization: [] + post: + description: |- + This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + + For more information about Subusers: + + * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) + * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + operationId: Create Subuser consumes: - application/json produces: - application/json - operationId: Create a batch ID - summary: Generate a new Batch ID to associate with scheduled sends - description: "Generate a new Batch ID to associate with scheduled sends via the mail/send endpoint.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" - security: - - {} - /contactdb/lists: - parameters: [] - get: - responses: - '200': - description: '' + parameters: + - name: body + in: body schema: - title: List All Lists response type: object properties: - lists: + username: + type: string + description: The username for this subuser. + email: + type: string + description: The email address of the subuser. + format: email + password: + type: string + description: The password this subuser will use when logging into SendGrid. + ips: type: array + description: The IP addresses that should be assigned to this subuser. items: - $ref: '#/definitions/contactdb_list' + type: string + format: ipv4 required: - - lists - examples: - application/json: - lists: - - id: 1 - name: the jones - recipient_count: 1 - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: List All Lists - summary: Returns an empty list if you GET and no lists exist on your account. - description: |- - Returns an empty list if you GET and no lists exist on your account. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - post: + - username + - email + - password + - ips responses: - '201': + '200': description: '' schema: - $ref: '#/definitions/contactdb_list' + $ref: '#/definitions/subuser_post' examples: application/json: - id: 1 - name: your list name - recipient_count: 0 + username: example_subuser + user_id: 1234 + email: example@example.com + signup_session_token: '' + authorization_token: '' + credit_allocation: + type: unlimited '400': - description: |- - "name" : "Returned if list name is a duplicate of an existing list or segment" - "name" : "Returned if list name is not a string" - "" : "Returned if request body is invalid JSON" + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: Returned if request body is invalid JSON - - field: name - message: Returned if list name is not a string - - field: name - message: Returned if list name is a duplicate of an existing list or segment + - message: username exists + - message: unable to validate IPs at this time '401': description: '' schema: @@ -6387,121 +5489,39 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - name: name - in: formData - required: true - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Create a List - summary: '' - description: |- - Create a list for your recipients. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - delete: - responses: - '204': + '403': description: '' - schema: - type: 'null' - '400': - description: '"id" : "Returned if all list ids are not valid"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: list id was invalid - '401': + - message: you dont have permission to access this resource + '500': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: {} examples: application/json: errors: - - field: null - message: authorization required - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Delete Multiple lists + - message: unable to validate IPs at this time summary: '' + security: + - Authorization: [] + /contactdb/recipients/count: + parameters: [] + get: description: |- - Delete multiple lists. - + Get a count of the current number of recipients in your contact database. The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - /asm/suppressions/global: - parameters: [] - post: - responses: - '200': - description: '' - schema: - type: object - properties: - recipient_emails: - type: array - items: - type: string - examples: - application/json: - recipient_emails: - - test1@example.com - - test2@example.com - parameters: - - type: string - name: recipient_emails - in: formData - description: '' + operationId: Get a Count of Recipients consumes: - application/json produces: - application/json - operationId: Add recipient addresses to the global suppression group. - summary: '' - description: Global Suppressions are email addresses that will not receive any emails. - security: - - {} - '/asm/suppressions/global/{email_address}': - parameters: [] - get: - responses: - '200': - description: '' - schema: - type: object - properties: - recipient_email: - type: string - examples: - application/json: - recipient_email: test1@example.com parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Check if a recipient address is in the global suppressions group. - summary: '' - description: Global Suppressions are email addresses that will not receive any emails. - security: - - {} - /contactdb/recipients/count: - parameters: [] - get: responses: '200': description: '' @@ -6519,162 +5539,247 @@ paths: errors: - field: null message: authorization required - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get a Count of Recipients summary: '' - description: |- - Get a count of the current number of recipients in your contact database. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). security: - - {} - /tracking_settings: - parameters: [] + - Authorization: [] + '/asm/suppressions/global/{email_address}': + parameters: + - name: email_address + in: path + required: true + type: string get: - responses: - '200': - description: '' - schema: - type: object - parameters: - - type: string - name: limit - in: query - - type: string - name: offset - in: query + description: Global Suppressions are email addresses that will not receive any emails. + operationId: Check if a recipient address is in the global suppressions group. consumes: - application/json produces: - application/json - operationId: Get Tracking Settings - summary: '' - description: '' - security: - - {} - /suppression/bounces: - parameters: [] - get: + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: number - email: - type: string - reason: - type: string - status: - type: string + type: object + properties: + recipient_email: + type: string examples: application/json: - - created: 1250337600 - email: example@example.com - reason: "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp " - status: 5.1.1 - - created: 1250337600 - email: example@example.com - reason: '550 5.1.1 : Recipient address rejected: User unknown in virtual alias table ' - status: 5.1.1 + recipient_email: test1@example.com + summary: '' + security: + - Authorization: [] + '/campaigns/{campaign_id}': + parameters: + - name: campaign_id + in: path + required: true + type: integer + delete: + description: |- + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Delete a Campaign + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '204': + description: '' + schema: + type: 'null' '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: {} examples: application/json: errors: - field: null message: authorization required - parameters: - - type: number - description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). - name: start_time - in: query - - type: number - description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). - name: end_time - in: query - - type: string - name: Allow - in: header - description: '' + '404': + description: '"": "not found"' + summary: '' + security: + - Authorization: [] + get: + description: |- + This is a place for notes and extra information about this endpoint. It is written + in Markdown - more info in the [documentation](/docs/designer#markdown). + + There are several special markdown helpers that automatically build tables + and html off of your endpoint definition. You can find some examples in this content. + + Click the "Open Editor" button above to start editing this content. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Get a single campaign consumes: - application/json produces: - application/json - operationId: List all bounces - summary: '' - description: "Bounces are messages that are returned to the server that sent it. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)" - security: - - {} - delete: + parameters: [] responses: - '204': + '200': description: '' schema: - type: 'null' + $ref: '#/definitions/campaign_response' + examples: + application/json: + id: 986724 + title: March Newsletter + subject: 'New Products for Spring!' + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content: '

Check out our spring line!

' + plain_content: 'Check out our spring line!' + status: Draft '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: {} examples: application/json: errors: - field: null message: authorization required - parameters: - - type: string - name: delete_all - in: formData - description: 'This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter.' - - type: string - name: emails - in: formData - description: Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter. + '404': + description: '"": "not found"' + examples: + application/json: + errors: + - field: null + message: not found + summary: '' + security: + - Authorization: [] + patch: + description: |- + Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Update a Campaign consumes: - application/json produces: - application/json - operationId: Delete bounces - summary: '' - description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes." - security: - - {} - /subusers: - parameters: [] - post: + parameters: + - name: body + in: body + schema: + title: Update a Campaign request + type: object + properties: + title: + type: string + description: The title of the campaign. + subject: + type: string + description: The subject line for your campaign. + categories: + type: array + description: The categories you want to tag on this campaign. + items: + type: string + html_content: + type: string + description: The HTML content of this campaign. + plain_content: + type: string + description: The plain content of this campaign. + required: + - title + - subject + - categories + - html_content + - plain_content responses: '200': description: '' schema: - $ref: '#/definitions/subuser_post' + $ref: '#/definitions/campaign_response' examples: application/json: - username: example_subuser - user_id: 1234 - email: example@example.com - signup_session_token: '' - authorization_token: '' - credit_allocation: - type: unlimited + id: 986724 + title: May Newsletter + subject: 'New Products for Summer!' + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - summer line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content: '

Check out our summer line!

' + plain_content: 'Check out our summer line!' + status: Draft '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + description: |- + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." examples: application/json: errors: - - message: username exists - - message: unable to validate IPs at this time + - field: title + message: "title can't be blank" + - field: title + message: title is too long (maximum is 100 characters) + - field: categories + message: categories exceeds 10 category limit + - field: html_content + message: html_content exceeds the 1MB limit + - field: plain_content + message: plain_content exceeds the 1MB limit + - field: sender_id + message: sender_id does not exist + - field: sender_id + message: sender_id is not a verified sender identity + - field: list_ids + message: list_ids do not all exist + - field: segment_ids + message: segment_ids do not all exist + - field: ip_pool + message: The ip pool you provided is invalid + - field: suppression_group_id + message: suppression_group_id does not exist + - field: unsubscribes + message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' + - field: null + message: The JSON you have submitted cannot be parsed. '401': description: '' schema: @@ -6685,161 +5790,86 @@ paths: - field: null message: authorization required '403': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: you dont have permission to access this resource - '500': - description: '' + description: '"": "You may only update a campaign when it is in draft mode."' schema: type: object properties: {} examples: application/json: errors: - - message: unable to validate IPs at this time - parameters: - - type: string - name: username - in: formData - required: true - description: The username for this subuser. - - type: string - name: email - in: formData - required: true - description: The email address of the subuser. - - type: string - name: password - in: formData - required: true - description: The password this subuser will use when logging into SendGrid. - - type: string - name: ips - in: formData - required: true - description: The IP addresses that should be assigned to this subuser. - consumes: - - application/json - produces: - - application/json - operationId: Create Subuser - summary: '' - description: |- - This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. - - For more information about Subusers: - - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - security: - - {} - get: - responses: - '200': - description: '' - schema: - type: array - items: - $ref: '#/definitions/subuser' - examples: - application/json: - - disabled: false - email: example@example.com - id: 1234 - username: example_subuser - - disabled: false - email: example2@example.com - id: 1234 - username: example_subuser2 - '401': - description: Unexpected error in API call. See HTTP response body for details. + - field: null + message: You may only update a campaign when it is in draft mode. + '404': + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: authorization required - parameters: - - type: string - description: The username of this subuser. - name: username - in: query - - type: number - description: The number of results you would like to get in each request. - name: limit - in: query - - type: number - description: The number of subusers to skip. - name: offset - in: query + - field: null + message: not found + summary: '' + security: + - Authorization: [] + /asm/suppressions/global: + parameters: [] + post: + description: Global Suppressions are email addresses that will not receive any emails. + operationId: Add recipient addresses to the global suppression group. consumes: - application/json produces: - application/json - operationId: List all Subusers - summary: '' - description: |- - This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. - - For more information about Subusers: - - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - security: - - {} - '/subusers/{subuser_name}/ips': - parameters: [] - put: - responses: - '200': - description: '' + parameters: + - name: body + in: body schema: type: object properties: - ips: + recipient_emails: type: array items: type: string - format: ipv4 - examples: - application/json: - ips: - - 127.0.0.1 - '401': + responses: + '201': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + recipient_emails: + type: array + items: + type: string examples: application/json: - errors: - - field: null - message: authorization required - parameters: - - type: string - name: subuser_name - in: query - required: true + recipient_emails: + - test1@example.com + - test2@example.com + summary: '' + security: + - Authorization: [] + '/mail/batch/{batch_id}': + parameters: + - name: batch_id + in: path + required: true + type: string + get: + description: "Validate whether or not a batch id is valid.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" + operationId: Validate batch ID consumes: - application/json produces: - application/json - operationId: Update IPs assigned to a subuser - summary: '' - description: "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)" - '/subusers/{subuser_name}': - parameters: [] - patch: + parameters: [] responses: - '204': + '200': description: '' schema: - type: object - properties: {} + $ref: '#/definitions/mail_batch_id' + examples: + application/json: + batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi '400': description: '' schema: @@ -6847,10 +5877,10 @@ paths: examples: application/json: errors: - - message: invalid username - - message: no fields provided + - field: null + message: invalid batch id '401': - description: '' + description: Unexpected error in API call. See HTTP response body for details. schema: $ref: '#/definitions/global:ErrorResponse' examples: @@ -6858,41 +5888,52 @@ paths: errors: - field: null message: authorization required - '500': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: unable to enable user - parameters: - - type: string - name: disabled - in: formData - description: 'Whether or not this subuser is disabled. True means disabled, False means enabled.' + summary: Validate whether or not a batch id is valid + security: + - Authorization: [] + /user/profile: + parameters: [] + patch: + description: |- + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + + It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. + operationId: "Update a user's profile" consumes: - application/json produces: - application/json - operationId: Enable/disable a subuser - summary: '' - description: |- - This endpoint allows you to enable or disable a subuser. - - For more information about Subusers: - - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - security: - - {} - delete: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/user_profile' + - name: on-behalf-of + in: header + description: "You can enter a subuser name as the value for this header, in order to update the subuser's profile." + type: string responses: - '204': + '200': description: '' schema: - type: object - properties: {} + $ref: '#/definitions/user_profile' + examples: + application/json: + address: 814 West Chapman Avenue + address2: '' + city: Orange + company: SendGrid + country: US + first_name: Example + last_name: User + phone: 555-555-5555 + state: CA + website: 'http://www.sendgrid.com' + zip: '92868' '401': description: '' schema: @@ -6902,1395 +5943,1642 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - description: The name of the subuser. - name: subuser_name - in: query - required: true - consumes: - - application/json - produces: - - application/json - operationId: Delete a subuser summary: '' + security: + - Authorization: [] + get: description: |- - This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - For more information about Subusers: + For more information about your user profile: - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - security: - - {} - '/subusers/{subuser_name}/monitor': - parameters: [] - get: + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: "Get a user's profile" + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/monitor' + title: GET User Profile response + type: object + properties: + address: + type: string + description: "The user's address." + address2: + type: string + description: "The second line of the user's address." + city: + type: string + description: "The user's city." + company: + type: string + description: "The name of the user's company." + country: + type: string + description: "The user's country." + first_name: + type: string + description: "The user's first name." + last_name: + type: string + description: "The user's last name." + phone: + type: string + description: "The user's phone number." + state: + type: string + description: "The user's state." + website: + type: string + description: "The user's website URL." + zip: + type: string + description: "The user's zip code." + required: + - address + - city + - company + - country + - first_name + - last_name + - phone + - state + - website + - zip examples: application/json: - email: example@example.com - frequency: 500 + address: 814 West Chapman Avenue + address2: '' + city: Orange + company: SendGrid + country: US + first_name: Test + last_name: User + phone: 555-555-5555 + state: CA + website: 'http://www.sendgrid.com' + zip: '92868' '401': description: '' + schema: + type: object + properties: {} + summary: '' + security: + - Authorization: [] + '/campaigns/{campaign_id}/schedules/test': + parameters: + - name: campaign_id + in: path + required: true + type: integer + post: + description: |- + To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Send a Test Campaign + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + to: + type: string + description: The email address that should receive the test campaign. + format: email + required: + - to + responses: + '204': + description: '' + schema: + title: Send a Test Campaign request + type: object + properties: + to: + type: string + required: + - to + '400': + description: |- + "": "The JSON you have submitted cannot be parsed." + "to": "Please provide an email address to which the test should be sent." + "to": "You can only send tests to 10 addresses at a time." + "subject": "Please add a subject to your campaign before sending a test." + "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." + "sender_id": "Please assign a sender identity to your campaign before sending a test." schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: + - field: send_at + message: Please choose a future time for sending your campaign. - field: null - message: authorization required + message: The JSON you have submitted cannot be parsed. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' '404': - description: '' + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: No monitor settings for this user - parameters: - - type: string - description: The name of the subuser for which to retrieve monitor settings. - name: subuser_name - in: query + message: not found + summary: 'To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"]' + security: + - Authorization: [] + /ips: + parameters: [] + get: + description: |- + See a list of all assigned and unassigned IPs. + Response includes warm up status, pools, assigned subusers, and whitelabel info. + The start_date field corresponds to when warmup started for that IP. + operationId: List all IPs consumes: - application/json produces: - application/json - operationId: Retrieve monitor settings for a subuser - summary: '' - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - security: - - {} - delete: + parameters: + - name: ip + in: query + description: The IP address to get + type: string + - name: exclude_whitelabels + in: query + description: Should we exclude whitelabels? + type: boolean + - name: subuser + in: query + description: The subuser you are requesting for. + type: string + - name: limit + in: query + description: The number of IPs you want returned at the same time. + type: integer + - name: offset + in: query + description: The offset for the number of IPs that you are requesting. + type: integer responses: - '204': - description: '' - schema: - type: object - properties: {} - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + type: object + properties: + ip: + type: string + subusers: + type: array + items: + type: string + rdns: + type: string + pools: + type: array + items: + type: string + warmup: + type: boolean + start_date: + type: + - number + - 'null' + whitelabeled: + type: boolean examples: application/json: - errors: - - field: null - message: authorization required - '404': + - ip: 127.0.0.1 + subusers: + - example_subuser1 + - example_subuser2 + rdns: o1.em.example.com + pools: [] + warmup: true + start_date: 1250337600 + whitelabeled: true + - ip: 127.0.0.1 + subusers: [] + pools: [] + warmup: false + start_date: null + whitelabeled: false + summary: |- + See a list of all assigned and unassigned IPs. + Response includes warm up status, pools, assigned subusers, and whitelabe + security: + - Authorization: [] + /whitelabel/links/default: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve the default link whitelabel.** + + Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: +
    +
  • Validated link whitelabels marked as "default"
    • +
  • Legacy link whitelabels (migrated from the whitelabel wizard)
    • +
  • Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net)
    • +
+ + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Retrieve a Default Link Whitelabel + consumes: + - application/json + produces: + - application/json + parameters: + - name: domain + in: query + description: The domain to match against when finding a corresponding link whitelabel. + type: string + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/link_whitelabel' examples: application/json: - errors: - - field: null - message: No monitor settings for this user - parameters: - - type: string - description: 'The name of the subuser from whom you would like to delete the monitor settings. ' - name: subuser_name - in: query - required: true + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + summary: 'Default link is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, th' + security: + - Authorization: [] + /tracking_settings/click: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your current click tracking setting.** + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Retrieve Click Track Settings consumes: - application/json produces: - application/json - operationId: Delete monitor settings - summary: '' - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - put: + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/monitor' + type: object + properties: + enable_text: + type: boolean + description: Indicates if click tracking is enabled for plain text emails. + enabled: + type: boolean + description: Indicates if click tracking is enabled or disabled. + required: + - enable_text + - enabled examples: application/json: - email: example@example.com - frequency: 500 - '400': + enable_text: false + enabled: true + summary: '' + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Update Click Tracking Settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: The setting you want to use for click tracking. + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + enable_text: + type: boolean + description: Indicates if click tracking is enabled for plain text emails + enabled: + type: boolean + description: The new setting new setting for click tracking. + required: + - enable_text + - enabled examples: application/json: - errors: - - field: email - message: Email is required - '401': + enable_text: false + enabled: true + summary: '' + security: + - Authorization: [] + /clients/stats: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your email statistics segmented by client type.** + + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: Retrieve email statistics by client type. + consumes: + - application/json + produces: + - application/json + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - errors: - - field: null - message: authorization required - parameters: [] + - date: '2014-10-01' + stats: + - metrics: + opens: 1 + unique_opens: 1 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: + opens: 0 + unique_opens: 0 + name: Gmail + type: client + summary: Gets email statistics by client type. + security: + - Authorization: [] + /mail_settings/spam_check: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your current Spam Checker mail settings.** + + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve spam check mail settings consumes: - application/json produces: - application/json - operationId: Update Monitor Settings for a subuser - summary: '' - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - security: - - {} - post: + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/monitor' - examples: - application/json: - email: example@example.com - frequency: 50000 - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: User already has a monitor - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_spam_check' examples: application/json: - errors: - - field: null - message: authorization required - parameters: [] + enabled: false + max_score: 6 + url: 'http://example.com' + summary: '' + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update your current spam checker mail settings.** + + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update spam check mail settings consumes: - application/json produces: - application/json - operationId: Create monitor settings - summary: '' - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - security: - - {} - '/contactdb/segments/{segment_id}/recipients': - parameters: [] - get: - responses: - '200': - description: '' + parameters: + - name: body + in: body schema: - title: List Recipients On a Segment response type: object properties: - recipients: - type: array - items: - type: object - properties: {} - required: - - recipients - '400': - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - '401': + enabled: + type: boolean + description: Indicates if you want the spam check mail setting to be enabled or not. + url: + type: string + description: The Inbound Parse URL where you would like your spam reports to be sent to. + max_score: + type: integer + default: 5 + description: 'The new max score, or spam threshold that you would like to set for the spam checker.' + minimum: 1 + maximum: 10 + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_spam_check' examples: application/json: - errors: - - field: null - message: authorization required - '404': - description: |- - "segment_id" : "Returned if segment_id is not valid" - "segment_id" : "Returned if segment_id does not exist" - parameters: - - type: string - name: page - in: query - - type: string - name: page_size - in: query - consumes: - - application/json - produces: - - application/json - operationId: List Recipients On a Segment + enabled: false + max_score: 6 + url: 'http://example.com' summary: '' - description: |- - List all of the recipients in a segment. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). security: - - {} - /whitelabel/ips: - parameters: [] - post: + - Authorization: [] + '/templates/{template_id}': + parameters: + - name: id + in: path + description: The id of the transactional template you want to delete. + required: true + type: string + delete: + description: | + **This endpoint allows you to delete a transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: Delete a template. + consumes: + - application/json + produces: [] + parameters: [] responses: - '201': + '204': description: '' schema: type: object - properties: - id: - type: integer - ip: - type: string - rnds: - type: string - users: - type: array - items: {} - subdomain: - type: string - domain: - type: string - valid: - type: boolean - legacy: - type: boolean - a_record: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - examples: - application/json: - id: 123 - ip: 192.168.1.2 - rnds: o1.email.example.com - users: [] - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.2 - parameters: - - type: string - name: ip - in: formData - description: '' - - type: string - name: subdomain - in: formData - description: '' - - type: string - name: domain - in: formData - description: '' + properties: {} + summary: '' + security: + - Authorization: [] + patch: + description: | + **This endpoint allows you to edit a transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: Edit a transactional template. consumes: - application/json produces: - application/json - operationId: Create an IP - summary: '' - description: '' - security: - - {} - get: + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name of the transactional template. + maxLength: 100 responses: '200': description: '' schema: - type: array - items: - type: object - properties: - id: - type: number - ip: - type: string - rdns: - type: string - users: - type: array - items: - properties: - user_id: - type: number - username: - type: string - subdomain: - type: string - domain: - type: string - a_record: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - valid: - type: boolean - legacy: - type: boolean + $ref: '#/definitions/transactional_template' examples: application/json: - - id: 1 - ip: 192.168.1.1 - rdns: o1.email.example.com - users: - - username: john@example.com - user_id: 7 - - username: jane@example.com - user_id: 8 - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.1 - - id: 2 - ip: 192.168.1.2 - rnds: o2.email.example.com - users: - - username: john@example.com - user_id: 7 - - username: jane@example2.com - user_id: 9 - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o2.email.example.com - data: 192.168.1.2 - parameters: - - type: string - name: limit - in: query + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: new_example_name + versions: [] + summary: '' + security: + - Authorization: [] + get: + description: | + **This endpoint allows you to retrieve a single transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: Retrieve a single transactional template. consumes: - application/json produces: - application/json - operationId: List all IPs + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/transactional_template' summary: '' - description: '' security: - - {} - /mail_settings: + - Authorization: [] + /mail_settings/bcc: parameters: [] get: + description: |- + **This endpoint allows you to retrieve your current BCC mail settings.** + + When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve all BCC mail settings + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - type: object - properties: - result: - type: array - items: - type: object - properties: - title: - type: string - enabled: - type: boolean - name: - type: string - description: - type: string + $ref: '#/definitions/mail_settings_bcc' examples: application/json: - result: - - title: Address Whitelist - enabled: false - name: address_whitelist - description: Address / domains that should never have email suppressed. - - title: BCC - enabled: false - name: bcc - description: Automatically BCC an address for every e-mail sent. - - title: Bounce Purge - enabled: false - name: bounce_purge - description: Allows you to automatically purge bounce records from SendGrid after a specified number of days. - - title: Event Notification - enabled: true - name: event_notify - description: 'Controls notifications for events, such as bounces, clicks, and opens.' - - title: Footer - enabled: false - name: footer - description: Allows you to add a custom footer to outgoing email. - - title: Forward Bounce - enabled: true - name: forward_bounce - description: Allows you to forward bounces to a specific email address. - - title: Forward Spam - enabled: false - name: forward_spam - description: Allows for a copy of spam reports to be forwarded to an email address. - - title: Legacy Email Template - enabled: true - name: template - description: Allows you to customize your outgoing HTML emails. - - title: Plain Content - enabled: false - name: plain_content - description: Convert your plain text emails to HTML. - - title: Spam Checker - enabled: true - name: spam_check - description: Check outbound messages for spam content. - parameters: - - type: string - name: limit - in: query - - type: string - name: offset - in: query + email: example@example.com + enabled: false + summary: '' + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update your current BCC mail settings.** + + When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update BCC mail settings consumes: - application/json produces: - application/json - operationId: Get all mail settings - summary: '' - description: '' - security: - - {} - '/asm/groups/{unsubscribe_group_id}': - parameters: [] - patch: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/mail_settings_patch' responses: '200': description: '' schema: - type: object - properties: - id: - type: number - name: - type: string - description: - type: string - last_email_sent_at: - type: - - string - - 'null' - _isOpen: true - is_default: - type: boolean + $ref: '#/definitions/mail_settings_patch' examples: application/json: - id: 1234 - name: A group name - description: A group description. - last_email_sent_at: null - is_default: true - parameters: - - type: string - name: id - in: formData - description: '' - - type: string - name: name - in: formData - description: '' - - type: string - name: description - in: formData - description: '' - - type: string - name: is_default - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Update unsubscribe groups + email: example@example.com + enabled: false summary: '' - description: '' security: - - {} - /templates: + - Authorization: [] + /ips/pools: parameters: [] post: - responses: - '201': - description: '' + description: '' + operationId: Create an IP pool. + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: type: object properties: - templates: - type: array - items: - properties: - id: - type: string - name: - type: string - versions: - type: array - items: - properties: {} + name: + type: string + responses: + '200': + description: '' + schema: + $ref: '#/definitions/ip_pool' examples: application/json: - id: 733ba07f-ead1-41fc-933a-3976baa23716 - name: example_name - versions: [] - parameters: - - type: string - name: name - in: formData - description: '' + name: marketing + summary: '' + security: + - Authorization: [] + get: + description: '' + operationId: List all IP pools. consumes: - application/json produces: - application/json - operationId: Create a template. + parameters: [] + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/ip_pool' + examples: + application/json: + - name: marketing + - name: transactional summary: '' - description: '' security: - - {} + - Authorization: [] + /contactdb/recipients/billable_count: + parameters: [] get: - responses: {} - parameters: [] + description: |- + You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Get the count of billable recipients consumes: - application/json - produces: [] - operationId: Retrieve all templates. + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contactdb_recipient_count' + examples: + application/json: + recipient_count: 1234 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required summary: '' - description: '' security: - - {} - '/whitelabel/ips/{id}/validate': + - Authorization: [] + /ips/warmup: parameters: [] post: + description: '' + operationId: Add an IP to warmup. + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + ip: + type: string responses: '200': description: '' schema: - type: object - properties: - id: - type: integer - valid: - type: boolean - validation_results: - type: object - properties: - a_record: - type: object - properties: - valid: - type: boolean - reason: - type: 'null' + type: array + items: + type: object + properties: + ip: + type: string + start_date: + type: integer examples: application/json: - id: 1 - valid: true - validation_results: - a_record: - valid: true - reason: null - '400': - description: Unexpected error in API call. See HTTP response body for details. - parameters: [] + - ip: 0.0.0.0 + start_date: 1409616000 + summary: '' + security: + - Authorization: [] + get: + description: '' + operationId: Get all IPs that are currently warming up. consumes: - application/json produces: - application/json - operationId: Validate an IP + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/ip_warmup_response' + examples: + application/json: + - ip: 0.0.0.0 + start_date: 1409616000 summary: '' - description: '' security: - - {} - /categories/stats/sums: + - Authorization: [] + /templates: parameters: [] get: + description: |- + **This endpoint allows you to retrieve all transactional templates.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: Retrieve all transactional templates. + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '200': description: '' + schema: + type: array + items: + $ref: '#/definitions/transactional_template' + summary: '' + security: + - Authorization: [] + post: + description: |- + **This endpoint allows you to create a transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: Create a transactional template. + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: type: object properties: - date: + name: type: string - stats: - type: array - items: - type: object - properties: {} + description: The name for the new transactional template. + maxLength: 100 + required: + - name + responses: + '201': + description: '' + schema: + $ref: '#/definitions/transactional_template' examples: application/json: - date: '2009-08-15' - stats: [] - parameters: - - type: string - name: sort_by_metric - in: query - - type: string - name: sort_by_direction - in: query - - type: string - name: start_date - in: query - required: true - - type: string - name: end_date - in: query - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: example_name + versions: [] + summary: '' + security: + - Authorization: [] + '/asm/groups/{group_id}/suppressions': + parameters: + - name: group_id + in: path + description: The id of the suppression group that you are retrieving email addresses from. + required: true + type: string + get: + description: |- + **This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.** + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: Retrieve all suppressions for a suppression group consumes: - application/json produces: - application/json - operationId: "Get sums of a category's stats [Needs: Stats object defined, has category ID?]" - summary: '' - description: '' - security: - - {} - /subusers/stats/sums: - parameters: [] - get: + parameters: [] responses: '200': description: '' schema: - type: object - properties: - date: - type: string - stats: - type: array - items: - properties: {} + type: array + items: + type: string examples: application/json: - date: '2015-10-11' - stats: [] - parameters: - - type: string - name: sort_by_direction - in: query - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query - - type: string - name: sort_by_metric - in: query + - example@example.com + - example2@example.com + summary: '' + security: + - Authorization: [] + post: + description: |- + **This endpoint allows you to add email addresses to an unsubscribe group.** + + If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list. + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: Add suppressions to a suppression group consumes: - application/json produces: - application/json - operationId: ' Gets the total sums of each email statistic metric for all subusers over the given date range.' - summary: '' - description: '' - security: - - {} - /user/account: - parameters: [] - get: + parameters: + - name: body + in: body + schema: + type: object + properties: + recipient_emails: + type: array + description: The email address that you want to add to the unsubscribe group. + items: + type: string + required: + - recipient_emails responses: - '200': + '201': description: '' schema: - title: GET User Account response type: object properties: - type: - type: string - description: The type of account for this user. - enum: - - free - - paid - reputation: - type: number - description: The sender reputation for this user. - required: - - type - - reputation + recipient_emails: + type: array + description: The email address that were added to the suppressions list. + items: + type: string examples: application/json: - reputation: 100 - type: paid - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: "Get a user's account information." + recipient_emails: + - test1@example.com + - test2@example.com summary: '' - description: "Your user's account information includes the user's account type and reputation." security: - - {} - /whitelabel/links/subuser: + - Authorization: [] + /asm/groups: parameters: [] - delete: - responses: - '204': - description: '' - parameters: - - type: string - name: username - in: query + get: + description: |- + **This endpoint allows you to retrieve a list of all suppression groups created by this user.** + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: Retrieve all suppression groups associated with the user. consumes: - application/json - produces: [] - operationId: Disassociate Link - summary: |- - Link Whitelabels can be associated with subusers via parent accounts. This functionality allows - subusers to send mail o - description: |- - Link Whitelabels can be associated with subusers via parent accounts. This functionality allows - subusers to send mail off their parent's Whitelabels. To associate a Whitelabel, the parent account - must first create a Whitelabel and validate it. Then the parent may associate the Whitelabel in - subuser management. - security: - - {} - get: + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - type: object - properties: - id: - type: integer - domain: - type: string - subdomain: - type: string - username: - type: string - user_id: - type: integer - default: - type: boolean - valid: - type: boolean - legacy: - type: boolean - dns: - type: object - properties: - domain_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - owner_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string + type: array + items: + $ref: '#/definitions/suppression_group_unsubscribes' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - parameters: - - type: string - name: username - in: query - required: true + - id: 1234 + name: Unsubscribe Group + description: An Unsubscribe Group + last_email_sent_at: null + is_default: true + unsubscribes: 1234 + - id: 1234 + name: Unsubscribe Group + description: An Unsubscribe Group + last_email_sent_at: null + is_default: true + unsubscribes: 1234 + summary: '' + security: + - Authorization: [] + post: + description: |- + **This endoint allows you to create a new suppression group.** + + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + + Each user can create up to 25 different suppression groups. + operationId: Create a Group consumes: - application/json produces: - application/json - operationId: List Associated Link - summary: '' - description: '' - security: - - {} - /categories: - parameters: [] - get: + parameters: + - name: body + in: body + schema: + title: Create a Group request + type: object + properties: + name: + type: string + description: The name of the new suppression group. May not share its name with any other suppression group on the user. + maxLength: 30 + description: + type: string + description: A description of the suppression group. + maxLength: 100 + is_default: + type: boolean + default: 'false' + description: Indicates if this is the default suppression group. + required: + - name + - description responses: '200': description: '' schema: - type: array - items: - type: object - properties: - category: - type: string + $ref: '#/definitions/suppression_group' examples: application/json: - - category: category 1 - - category: category 2 - parameters: - - type: string - name: limit - in: query - - type: string - name: sort_by - in: query - - type: string - name: order - in: query + id: 1234 + name: A group name + description: A group description + last_email_sent_at: null + is_default: false + summary: '' + security: + - Authorization: [] + '/asm/groups/{group_id}/suppressions/{email}': + parameters: + - name: group_id + in: path + description: The id of the suppression group that you are removing an email address from. + required: true + type: string + - name: email + in: path + description: The email address that you want to remove from the suppression group. + required: true + type: string + delete: + description: |- + **This endpoint allows you to remove a suppressed email address from the given suppression group.** + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: Delete a suppression from a suppression group consumes: - application/json - produces: - - application/json - operationId: Get categories + produces: [] + parameters: [] + responses: + '204': + description: '' + schema: + type: 'null' summary: '' - description: '' security: - - {} - /browsers/stats: - parameters: [] - get: + - Authorization: [] + '/ips/warmup/{ip_address}': + parameters: + - name: ip_address + in: path + required: true + type: string + delete: + description: '' + operationId: Remove an IP from warmup. + consumes: + - application/json + produces: [] + parameters: [] responses: - '200': + '204': description: '' schema: - type: array - items: - type: object - properties: {} - parameters: - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query + type: object + properties: {} + summary: '' + security: + - Authorization: [] + get: + description: '' + operationId: Get warmup status for a particular IP. consumes: - application/json produces: - application/json - operationId: 'Gets email statistics by browser. ' - summary: '' - description: '' - security: - - {} - /user/webhooks/parse/stats: - parameters: [] - get: + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - date: - type: string - stats: - type: array - items: - properties: - metrics: - type: object - properties: - received: - type: number - examples: - application/json: - - date: '2015-10-11' - stats: - - metrics: - received: 0 - - date: '2015-10-12' - stats: - - metrics: - received: 0 - - date: '2015-10-13' - stats: - - metrics: - received: 0 - - date: '2015-10-14' - stats: - - metrics: - received: 0 - - date: '2015-10-15' - stats: - - metrics: - received: 0 - - date: '2015-10-16' - stats: - - metrics: - received: 0 - - date: '2015-10-17' - stats: - - metrics: - received: 0 - - date: '2015-10-18' - stats: - - metrics: - received: 0 - - date: '2015-10-19' - stats: - - metrics: - received: 0 - - date: '2015-10-20' - stats: - - metrics: - received: 0 - - date: '2015-10-21' - stats: - - metrics: - received: 0 - - date: '2015-10-22' - stats: - - metrics: - received: 0 - - date: '2015-10-23' - stats: - - metrics: - received: 0 - - date: '2015-10-24' - stats: - - metrics: - received: 0 - - date: '2015-10-25' - stats: - - metrics: - received: 0 - - date: '2015-10-26' - stats: - - metrics: - received: 0 - - date: '2015-10-27' - stats: - - metrics: - received: 0 - - date: '2015-10-28' - stats: - - metrics: - received: 0 - - date: '2015-10-29' - stats: - - metrics: - received: 0 - - date: '2015-10-30' - stats: - - metrics: - received: 0 - - date: '2015-10-31' - stats: - - metrics: - received: 0 - - date: '2015-11-01' - stats: - - metrics: - received: 0 - - date: '2015-11-02' - stats: - - metrics: - received: 0 - - date: '2015-11-03' - stats: - - metrics: - received: 0 - - date: '2015-11-04' - stats: - - metrics: - received: 0 - - date: '2015-11-05' - stats: - - metrics: - received: 0 - - date: '2015-11-06' - stats: - - metrics: - received: 0 - - date: '2015-11-07' - stats: - - metrics: - received: 0 - - date: '2015-11-08' - stats: - - metrics: - received: 0 - - date: '2015-11-09' - stats: - - metrics: - received: 0 - - date: '2015-11-10' - stats: - - metrics: - received: 0 - parameters: - - type: string - name: limit - in: query - - type: string - name: offset - in: query - - type: string - name: aggregated_by - in: query - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query + $ref: '#/definitions/ip_warmup_response' + summary: '' + security: + - Authorization: [] + /contactdb/reserved_fields: + parameters: [] + get: + description: |- + List fields that are reserved and can't be used for custom field names. [GET] + + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: Get reserved custom fields fields. consumes: - application/json produces: - application/json - operationId: Gets statistics for Parse Webhook usage. - summary: '' - description: '' - security: - - {} - /mail_settings/footer: - parameters: [] - patch: + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_footer' + title: "List fields that are reserved and can't be used for custom field names. response" + type: object + properties: + reserved_fields: + type: array + description: The reserved fields that are already set up within custom fields. + items: + $ref: '#/definitions/contactdb_custom_field' + required: + - reserved_fields + examples: + application/json: + reserved_fields: + - name: first_name + type: text + - name: last_name + type: text + - name: email + type: text + - name: created_at + type: date + - name: updated_at + type: date + - name: last_emailed + type: date + - name: last_clicked + type: date + - name: last_opened + type: date + - name: my_custom_field + type: text + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content - parameters: [] + errors: + - field: null + message: authorization required + summary: '' + security: + - Authorization: [] + /campaigns: + parameters: [] + get: + description: |- + Returns campaigns in reverse order they were created (newest first). + + Returns an empty array if no campaigns exist. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Get all Campaigns consumes: - application/json produces: - application/json - operationId: Update footer mail settings - summary: '' - description: '' - security: - - {} - get: + parameters: + - name: limit + in: query + description: The number of results you would like to receive at a time. + type: number + - name: offset + in: query + description: 'The index of the first campaign to return, where 0 is the first campaign.' + type: number responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_footer' + type: object + properties: + result: + type: array + _isOpen: true + items: + $ref: '#/definitions/campaign_response' examples: application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content - parameters: [] + result: + - id: 986724 + title: March Newsletter + subject: 'New Products for Spring!' + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content: '

Check out our spring line!

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

Last call for winter clothes!

' + plain_content: 'Last call for winter clothes!' + status: Sent + summary: |- + Returns campaigns in reverse order they were created (newest first) + Returns an empty array if no campaigns exist + security: + - Authorization: [] + post: + description: |- + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + + + Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Create a Campaign consumes: - application/json produces: - application/json - operationId: 'Get footer mail settings [params can be null?]' - summary: '' - description: '' - security: - - {} - /mail_settings/template: - parameters: [] - patch: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/campaign_request' responses: - '200': + '201': description: '' schema: - type: object - properties: - enabled: - type: boolean - html_content: - type: string + $ref: '#/definitions/campaign_response' examples: application/json: - enabled: false - html_content: | -

<% body %>Example

- parameters: - - type: string - name: enabled - in: formData - description: '' - - type: string - name: html_content - in: formData + id: 986724 + title: March Newsletter + subject: 'New Products for Spring!' + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content: '

Check out our spring line!

' + plain_content: 'Check out our spring line!' + status: Draft + '400': + description: |- + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." + "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: title + message: "title can't be blank" + - field: title + message: title is too long (maximum is 100 characters) + - field: categories + message: categories exceeds 10 category limit + - field: html_content + message: html_content exceeds the 1MB limit + - field: plain_content + message: plain_content exceeds the 1MB limit + - field: sender_id + message: sender_id does not exist + - field: sender_id + message: sender_id is not a verified sender identity + - field: list_ids + message: list_ids do not all exist + - field: segment_ids + message: segment_ids do not all exist + - field: ip_pool + message: The ip pool you provided is invalid + - field: suppression_group_id + message: suppression_group_id does not exist + - field: unsubscribes + message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' + - field: null + message: The JSON you have submitted cannot be parsed. + - field: null + message: "You've reached your limit of 250 campaigns. Please delete one or more and try again." + '401': description: '' + schema: + type: object + properties: {} + summary: |- + {% info %} + A campaign requires a title to be created. + In order to send or schedule the campaign, you will be required to + security: + - Authorization: [] + /subusers/reputations: + parameters: [] + get: + description: |- + Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will effect your sender rating. + + This endpoint allows you to request the reputations for your subusers. + operationId: Retrieve Subuser Reputations consumes: - application/json produces: - application/json - operationId: Update template mail settings - summary: '' - description: '' - security: - - {} - get: + parameters: + - name: usernames + in: query + type: string responses: '200': description: '' schema: - type: object - properties: - enabled: - type: boolean - html_content: - type: string + type: array + items: + type: object + properties: + reputation: + type: number + description: The sender reputation this subuser has attained. + username: + type: string + description: The subuser that has this reputation.f + required: + - reputation + - username examples: application/json: - enabled: false - html_content: | -

<% body %>Example

- parameters: [] + - username: example_subuser + reputation: 99 + - username: example_subuser2 + reputation: 95.2 + '401': + description: '' + schema: + type: object + properties: {} + summary: '' + security: + - Authorization: [] + '/whitelabel/ips/{id}': + parameters: + - name: id + in: path + description: The id of the IP whitelabel that you would like to retrieve. + required: true + type: string + get: + description: |- + **This endpoint allows you to retrieve an IP whitelabel.** + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: Retrieve an IP whitelabel consumes: - application/json produces: - application/json - operationId: Get template mail settings - summary: '' - description: '' - security: - - {} - /partner_settings: - parameters: [] - get: + parameters: [] responses: '200': + description: '' + schema: + $ref: '#/definitions/ip_whitelabel' + examples: + application/json: + id: 123 + ip: 192.168.1.1 + rdns: o1.email.example.com + users: + - username: john@example.com + user_id: 7 + subdomain: email + domain: example.com + valid: true + legacy: false + a_record: + valid: true + type: a + host: o1.email.example.com + data: 192.168.1.1 + '404': description: '' schema: type: object properties: - result: + errors: type: array - _isOpen: true + description: The errors preventing the retrieval of the IP whitelabel. items: type: object properties: - title: - type: string - enabled: - type: boolean - name: - type: string - description: + message: type: string + description: A message explaining why the IP whitelabel could not be found. + required: + - message + required: + - errors examples: application/json: - result: - - title: Partner title - enabled: true - name: partner_name - description: A description of a partner. - parameters: - - type: string - name: limit - in: query - - type: string - name: undefined - in: query + errors: + - message: Whitelabel ip not found. + summary: '' + security: + - Authorization: [] + delete: + description: |- + **This endpoint allows you to delete an IP whitelabel.** + + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: Delete an IP whitelabel consumes: - application/json produces: - application/json - operationId: Get partner settings - summary: '' - description: '' - security: - - {} - '/suppression/bounces/{email}': - parameters: [] - delete: + parameters: [] responses: '204': description: '' schema: type: object properties: {} - '401': + '404': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + errors: + type: array + description: The errors preventing the IP whitelabel from being deleted. + items: + type: object + properties: + message: + type: string + description: A message explaining why the IP whitelabel could not be deleted. examples: application/json: errors: - - field: null - message: authorization required - parameters: - - type: string - description: The email address you would like to remove from the bounce list. - format: email - name: email_address - in: query - required: true + - message: Whitelabel ip not found. + summary: '' + security: + - Authorization: [] + /mail_settings/bounce_purge: + parameters: [] + patch: + description: |- + **This endpoint allows you to update your current bounce purge settings.** + + This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Update bounce purge mail settings consumes: - application/json produces: - application/json - operationId: Delete a bounce - summary: '' - description: "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)" - security: - - {} - get: + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/mail_settings_bounce_purge' responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - email: - type: string - reason: - type: string - status: - type: string + $ref: '#/definitions/mail_settings_bounce_purge' examples: application/json: - - created: 1443651125 - email: bounce1@test.com - reason: "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp " - status: 5.1.1 - parameters: [] + enabled: false + hard_bounces: null + soft_bounces: null + summary: '' + security: + - Authorization: [] + get: + description: |- + **This endpoint allows you to retrieve your current bounce purge settings.** + + This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve bounce purge mail settings consumes: - application/json produces: - application/json - operationId: Get a Bounce + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/mail_settings_bounce_purge' + examples: + application/json: + enabled: false + soft_bounces: 1234 + hard_bounces: null summary: '' - description: '' security: - - {} + - Authorization: [] /whitelabel/links: parameters: [] - get: + post: + description: |- + **This endpoint allows you to create a new link whitelabel.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Create a Link Whitelabel + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: Number of domains to return. + type: integer + - name: offset + in: query + description: Paging offset. + type: integer + - name: body + in: body + schema: + type: object + properties: + domain: + type: string + description: The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address. + subdomain: + type: string + description: The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel. + default: + type: boolean + description: 'Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.' + enum: + - true + - false + required: + - domain + - subdomain responses: - '200': + '201': description: '' schema: - type: array - items: - type: object - properties: - id: - type: integer - domain: - type: string - subdomain: - type: string - username: - type: string - user_id: - type: integer - default: - type: boolean - valid: - type: boolean - legacy: - type: boolean - dns: - type: object - properties: - domain_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - owner_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string + $ref: '#/definitions/link_whitelabel' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + summary: '' + security: + - Authorization: [] + get: + description: |- + **This endpoint allows you to retrieve all link whitelabels.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Retrieve all link whitelabels + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: Limits the number of results returned per page. + type: integer + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/link_whitelabel' examples: application/json: - id: 1 @@ -8331,1213 +7619,2370 @@ paths: type: cname host: 8.example2.com data: sendgrid.net - parameters: - - type: string - name: limit - in: query + summary: '' + security: + - Authorization: [] + /user/settings/enforced_tls: + parameters: [] + patch: + description: '' + operationId: Change the Enforced TLS settings consumes: - application/json produces: - application/json - operationId: List all Links + parameters: + - name: body + in: body + schema: + type: object + properties: + require_tls: + type: boolean + require_valid_cert: + type: boolean + responses: + '200': + description: '' + schema: + type: object + properties: + require_tls: + type: boolean + require_valid_cert: + type: boolean + examples: + application/json: + require_tls: true + require_valid_cert: false summary: '' + security: + - Authorization: [] + get: description: '' + operationId: Get the current Enforced TLS settings. + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + require_tls: + type: boolean + require_valid_cert: + type: boolean + examples: + application/json: + require_tls: false + require_valid_cert: false + summary: '' security: - - {} + - Authorization: [] + /mail/batch: + parameters: [] post: + description: "Generate a new Batch ID to associate with scheduled sends via the mail/send endpoint.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)" + operationId: Create a batch ID + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '201': + description: '' + schema: + $ref: '#/definitions/mail_batch_id' + examples: + application/json: + batch_id: YOUR_BATCH_ID + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: Generate a new Batch ID to associate with scheduled sends + security: + - Authorization: [] + '/subusers/{subuser_name}/ips': + parameters: + - name: subuser_name + in: path + required: true + type: string + put: + description: "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)" + operationId: Update IPs assigned to a subuser + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + ips: + type: array + items: + type: string + format: ipv4 + examples: + application/json: + ips: + - 127.0.0.1 + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: '' + /api_keys: + parameters: [] + get: + description: 'The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).' + operationId: List all API Keys belonging to the authenticated user + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + _isOpen: true + items: + $ref: '#/definitions/api_key_name_id' + examples: + application/json: + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + summary: "**List all API Keys belonging to the authenticated user**\n\nThe API Keys feature allows customers to be able to generate " + security: + - Authorization: [] + '/whitelabel/domains/{id}/validate': + parameters: + - name: id + in: path + required: true + type: string + post: + description: |- + **This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer |ID of the domain whitelabel to validate. | + operationId: Validate a domain whitelabel. + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': description: '' schema: type: object properties: id: type: integer - domain: - type: string - subdomain: - type: string - username: - type: string - user_id: - type: integer - default: - type: boolean + description: The ID of the domain whitelabel. valid: type: boolean - legacy: - type: boolean - dns: + description: Indicates if this is a valid whitelabel. + validation_resuts: type: object + description: 'The individual DNS records that are checked when validating, including the reason for any invalid DNS records.' properties: - domain_cname: + mail_cname: type: object + description: The CNAME record for the domain whitelabel. properties: valid: type: boolean - type: - type: string - host: - type: string - data: + description: Indicates if this DNS record is valid. + reason: type: string - owner_cname: + description: The reason this record is invalid. + dkim1: type: object + description: A DNS record for this domain whitelabel. properties: valid: type: boolean - type: - type: string - host: - type: string - data: - type: string + description: Indicates if the DNS record is valid. + reason: + type: 'null' + dkim2: + type: object + description: A DNS record for this whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + reason: + type: 'null' + spf: + type: object + description: The SPF record for the whitelabel. + properties: + valid: + type: boolean + description: Indicates if the SPF record is valid. + reason: + type: 'null' examples: application/json: id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false valid: true - legacy: false - dns: - domain_cname: + validation_resuts: + mail_cname: + valid: false + reason: 'Expected your MX record to be "mx.sendgrid.net" but found "example.com".' + dkim1: valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: + reason: null + dkim2: valid: true - type: cname - host: 7.example.com - data: sendgrid.net - parameters: - - type: number - description: Number of domains to return. Defaults to 50. - name: limit - in: query - - type: number - description: Paging offset. Defaults to 0. - name: offset - in: query - - type: string - name: domain - in: formData - description: '' - - type: string - name: subdomain - in: formData - description: '' - - type: string - name: default - in: formData + reason: null + spf: + valid: true + reason: null + '400': + description: Unexpected error in API call. See HTTP response body for details. + schema: + type: object + properties: {} + '500': description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + description: A message explaining the reason for the error. + required: + - message + examples: + application/json: + errors: + - message: internal error getting TXT + summary: '' + security: + - Authorization: [] + /devices/stats: + parameters: [] + get: + description: "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html)." + operationId: Retrieve email statistics by device type. consumes: - application/json produces: - application/json - operationId: Create a Link + parameters: + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string + - name: limit + in: query + description: How many results to include on each page. + required: false + type: integer + - name: offset + in: query + description: How many results to exclude. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + - name: start_date + in: query + description: The starting date of the statistics to retrieve. + required: true + type: string + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/advanced_stats_opens' + examples: + application/json: + - date: '2015-10-11' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-12' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-13' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-14' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-15' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-16' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-17' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-18' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-19' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-20' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-21' + stats: + - type: device + name: Webmail + metrics: + opens: 1 + unique_opens: 1 + - date: '2015-10-22' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-23' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-24' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-25' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-26' + stats: + - type: device + name: Webmail + metrics: + opens: 2 + unique_opens: 2 + - date: '2015-10-27' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-28' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-29' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-30' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-10-31' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-01' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-02' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-03' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-04' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-05' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-06' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-07' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-08' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-09' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 + - date: '2015-11-10' + stats: + - type: device + name: Webmail + metrics: + opens: 0 + unique_opens: 0 summary: '' - description: |- - This is a place for notes and extra information about this endpoint. It is written - in Markdown - more info in the [documentation](/docs/designer#markdown). - - There are several special markdown helpers that automatically build tables - and html off of your endpoint definition. You can find some examples in this content. - - Click the "Open Editor" button above to start editing this content. security: - - {} - /tracking_settings/google_analytics: + - Authorization: [] + /scopes: parameters: [] get: - responses: - '200': - description: '' - schema: - type: object - properties: - enabled: - type: boolean - utm_campaign: - type: string - utm_content: - type: string - utm_medium: - type: string - utm_source: - type: string - utm_term: - type: string - examples: - application/json: - enabled: true - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' - parameters: [] + description: "**This endpoint returns a list of all scopes that this user has access to.**\n\nAPI Keys can be used to authenticate the use of [SendGrid’s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). " + operationId: Returns a list of scopes for which this user has access. consumes: - application/json produces: - application/json - operationId: Get Google Analytics Settings - summary: '' - description: '' - security: - - {} - patch: + parameters: [] responses: '200': description: '' schema: type: object properties: - enabled: - type: boolean - utm_campaign: - type: string - utm_content: - type: string - utm_medium: - type: string - utm_source: - type: string - utm_term: - type: string - examples: - application/json: - enabled: false - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' - parameters: - - type: string - name: enabled - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Update Google Analytics Settings - summary: '' - description: '' - security: - - {} - /user/scheduled_sends: - parameters: [] - get: - responses: - '200': - description: '' - schema: - type: array - items: - $ref: '#/definitions/user_scheduled_send_status' + scopes: + type: array + description: The list of scopes for which this user has access. + uniqueItems: true + items: + type: string + required: + - scopes examples: application/json: - - batch_id: YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg - status: cancel - - batch_id: UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2 - status: cancel + scopes: + - mail.send + - alerts.create + - alerts.read '401': description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Get all scheduled sends - summary: '' - description: |- - Get all cancel/paused scheduled send information. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - security: - - {} - post: - responses: - '201': - description: '' - schema: - $ref: '#/definitions/user_scheduled_send_status' - '400': - description: |- - "" : "max limit reached" - "batch_id" : "invalid batch id" - "batch_id" : "a status for this batch id exists, try PATCH to update the status" schema: type: object - properties: {} - examples: - application/json: + properties: errors: - - field: null - message: max limit reached - - field: batch_id - message: invalid batch id - - field: batch_id - message: 'a status for this batch id exists, try PATCH to update the status' - '401': - description: '' - schema: - type: object - properties: {} + type: array + description: "This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes." + items: + type: object + properties: + field: + type: 'null' + description: "This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required." + message: + type: string + description: Explains why the scopes cannot be returned. + required: + - message + required: + - errors examples: application/json: errors: - field: null message: authorization required - parameters: - - type: string - name: batch_id - in: formData - required: true - description: The batch ID is the identifier that your scheduled mail sends share. - - type: string - name: status - in: formData - required: true - description: 'The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}' - consumes: - - application/json - produces: - - application/json - operationId: Cancel or pause a scheduled send - summary: |- - Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will - be returned. - description: |- - Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will - be returned. - - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - security: - - {} - /mail_settings/plain_content: - parameters: [] - patch: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings::patch' - examples: - application/json: - enabled: false - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Update plain content mail settings summary: '' - description: '' security: - - {} + - Authorization: [] + /geo/stats: + parameters: [] get: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings::patch' - examples: - application/json: - enabled: false - parameters: [] + description: |- + **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** + + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: Retrieve email statistics by country and state/province. consumes: - application/json produces: - application/json - operationId: Get plain content mail settings - summary: '' - description: '' - security: - - {} - /categories/stats: - parameters: [] - get: - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - date: - type: string - stats: - type: array - items: - properties: - type: - type: string - name: - type: string - metrics: - type: object - properties: - blocks: - type: number - bounce_drops: - type: number - bounces: - type: number - clicks: - type: number - deferred: - type: number - delivered: - type: number - invalid_emails: - type: number - opens: - type: number - processed: - type: number - requests: - type: number - spam_report_drops: - type: number - spam_reports: - type: number - unique_clicks: - type: number - unique_opens: - type: number - unsubscribe_drops: - type: number - unsubscribes: - type: number + parameters: + - name: limit + in: query + description: How many results to include on each page. + required: false + type: integer + - name: offset + in: query + description: How many results to exclude. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How you would like the statistics to be grouped. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: 'The end date of the statistics to retrieve. ' + required: false + type: string + - name: country + in: query + description: The country you would like to see statistics for. Currently only supported for US and CA. + required: false + type: string + enum: + - US + - CA + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/advanced_stats_country' examples: application/json: - - date: '2015-10-01' + - date: '2015-10-11' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-12' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-13' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-14' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-15' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-16' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-17' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-18' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-19' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-20' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-21' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 1 + unique_clicks: 0 + unique_opens: 1 + - date: '2015-10-22' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-23' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-24' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-25' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-26' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-27' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-28' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-29' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-30' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-31' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-01' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-02' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-03' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-04' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-05' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-06' + stats: + - type: province + name: TX + metrics: + clicks: 0 + opens: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-07' stats: - - type: category - name: docs + - type: province + name: TX metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - type: category - name: mattscategory + - date: '2015-11-08' + stats: + - type: province + name: TX metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-01' + - date: '2015-11-09' stats: - - type: category - name: docs + - type: province + name: TX metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - type: category - name: mattscategory + - date: '2015-11-10' + stats: + - type: province + name: TX metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 unique_clicks: 0 unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 + summary: '' + /whitelabel/domains: + parameters: [] + post: + description: |- + **This endpoint allows you to create a whitelabel for one of your domains.** + + If you are creating a domain whitelabel that you would like a subuser to use, you have two options: + 1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. + 2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: Create a domain whitelabel. + consumes: + - application/json + produces: + - application/json parameters: - - type: string - name: start_date - in: query - required: true - - type: string - name: end_date + - name: body + in: body + schema: + type: object + properties: + domain: + type: string + description: Domain being whitelabeled. + subdomain: + type: string + description: The subdomain to use for this domain whitelabel. + username: + type: string + description: The username that this whitelabel will be associated with. + ips: + type: array + description: The IP addresses that will be included in the custom SPF record for this whitelabel. + items: + type: string + custom_spf: + type: boolean + description: Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security. + default: + type: boolean + description: "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain." + automatic_security: + type: boolean + description: 'Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.' + required: + - domain + - subdomain + responses: + '201': + description: '' + schema: + $ref: '#/definitions/whitelabel::domain' + examples: + application/json: + id: 302183 + user_id: 1446226 + subdomain: example + domain: example.com + username: mbernier + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_cname: + valid: false + type: cname + host: example.example.com + data: u1446226.wl.sendgrid.net + dkim1: + valid: false + type: cname + host: s1._domainkey.example.com + data: s1.domainkey.u1446226.wl.sendgrid.net + dkim2: + valid: false + type: cname + host: s2._domainkey.example.com + data: s2.domainkey.u1446226.wl.sendgrid.net + summary: |- + When creating a whitelabel for a subuser, there are two options available: + Use the "username" parameter. This allows + security: + - Authorization: [] + get: + description: | + **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: List all domain whitelabels. + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit in: query - - type: string - name: categories + description: Number of domains to return. + type: integer + - name: offset in: query - required: true - - type: string - name: limit + description: Paging offset. + type: integer + - name: exclude_subusers in: query - - type: string - name: offset + description: Exclude subuser domains from the result. + type: boolean + - name: username in: query - - type: string - name: aggregated_by + description: The username associated with a whitelabel. + type: string + - name: domain in: query + description: Search for domain whitelabels that match the given domain. + type: string + responses: + '200': + description: '' + schema: + type: array + items: + type: object + properties: + id: + type: number + description: The ID of the domain whitelabel. + user_id: + type: number + description: The ID of the user that this whitelabel will be associated with. + subdomain: + type: string + description: The subdomain created for this domain whitelabel. + domain: + type: string + description: The domain that this whitelabel was created for. + username: + type: string + description: The username that this whitelabel is associated with. + ips: + type: array + description: The IPs that will be included in the custom SPF record. + items: + type: string + custom_spf: + type: boolean + description: Indicates if this whitelabel has custom SPF. + default: + type: boolean + description: Indicates if this whitelabel has been set as the default whitelabel. + legacy: + type: boolean + description: Indicates if this is whitelabel was created with the legacy whitelabel tool. + automatic_security: + type: boolean + description: Indicates if this whitelabel uses automated security. + valid: + type: boolean + description: Indicates if this is a valid whitelabel or not. + dns: + type: object + description: The DNS records for this whitelabel that are used for authenticating the sending domain. + properties: + mail_server: + type: object + description: Designates which mail server is responsible for accepting messages from a domain. + properties: + valid: + type: boolean + description: Indicates if this is a valid DNS record with no conflicts. + type: + type: string + description: The type of DNS record. + host: + type: string + description: The domain sending the messages. + data: + type: string + description: The mail server responsible for accepting messages. + subdomain_spf: + type: object + description: The SPF record for the subdomain used to create this whitelabel. + properties: + valid: + type: boolean + description: Indicates if the SPF record is valid. + type: + type: string + description: The type of data in the SPF record. + host: + type: string + description: The domain that this SPF record will be used to authenticate. + data: + type: string + description: The SPF record. + dkim: + type: object + description: The DNS record used when creating the DKIM signature. + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + type: + type: string + description: The type of DNS record. + enum: + - cname + - mx + - txt + host: + type: string + description: The domain that these DNS records will be applied to. + format: hostname + data: + type: string + description: The DNS record. + required: + - id + - user_id + - subdomain + - domain + - username + - ips + - custom_spf + - default + - legacy + - automatic_security + - valid + - dns + examples: + application/json: + - id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + legacy: false + automatic_security: true + valid: true + dns: + mail_cname: + host: mail.example.com + type: cname + data: u7.wl.sendgrid.net + valid: true + spf: + host: example.com + type: txt + data: 'v=spf1 include:u7.wl.sendgrid.net -all' + valid: true + dkim1: + host: s1._domainkey.example.com + type: cname + data: s1._domainkey.u7.wl.sendgrid.net + valid: true + dkim2: + host: s2._domainkey.example.com + type: cname + data: s2._domainkey.u7.wl.sendgrid.net + valid: true + - id: 2 + domain: example2.com + subdomain: news + username: jane@example2.com + user_id: 8 + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_server: + host: news.example2.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: news.example2.com + type: txt + data: 'v=spf1 include:sendgrid.net ~all' + valid: false + domain_spf: + host: example2.com + type: txt + data: 'v=spf1 include:news.example2.com -all' + valid: false + dkim: + host: example2.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false + summary: '' + security: + - Authorization: [] + '/campaigns/{campaign_id}/schedules/now': + parameters: + - name: campaign_id + in: path + required: true + type: integer + post: + description: |- + Send your campaign right now. Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, we don't need a body. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: Send a Campaign consumes: - application/json produces: - application/json - operationId: Category Stats provide all of your user’s email statistics for your categories. - summary: '' - description: '' - security: - - {} - '/whitelabel/links/{id}/validate': - parameters: [] - post: + parameters: [] responses: - '200': + '201': description: '' schema: + title: Send a Campaign response type: object properties: id: type: integer - valid: - type: boolean - validation_results: - type: object - properties: - domain_cname: - type: object - properties: - valid: - type: boolean - reason: - type: string - owner_cname: - type: object - properties: - valid: - type: boolean - reason: - type: 'null' + format: int64 + status: + type: string + required: + - id + - status examples: application/json: - id: 1 - valid: true - validation_results: - domain_cname: - valid: false - reason: 'Expected CNAME to match "sendgrid.net." but found "example.com.".' - owner_cname: - valid: true - reason: null + id: 1234 + status: Scheduled '400': - description: Unexpected error in API call. See HTTP response body for details. - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Validate a Link - summary: '' - description: '' - security: - - {} - '/clients/{client_type}/stats': - parameters: [] - get: - responses: - '200': - description: '' + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" schema: - $ref: '#/definitions/stats' - parameters: - - type: string - name: start_date - in: query - - type: string - name: end_date - in: query - - type: string - name: aggregated_by - in: query - consumes: - - application/json - produces: - - application/json - operationId: Retrieve stats by a specific client type - summary: Gets email statistics by a single client type. - description: Gets email statistics by a single client type. - security: - - {} - /ips/assigned: - parameters: [] - get: - responses: - '200': + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: subject + message: "subject can't be blank" + - field: sender_id + message: "sender_id can't be blank" + - field: plain_content + message: "plain_content can't be blank, please provide plain text or html content" + - field: list_id + message: You must select at least 1 segment or 1 list to send to. + - field: unsubscribe_tag + message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' + - field: suppression_group_id + message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + '401': description: '' schema: - title: List all assigned IPs response - type: object - properties: - ip: - type: string - pools: - type: array - items: - type: string - warmup: - type: boolean - start_date: - type: integer - format: int64 - required: - - ip - - pools - - warmup - - start_date - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: List all assigned IPs - summary: See only assigned IPs. - description: Retrieve a list of your IP addresses. + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '403': + description: '"": "You may only send a campaign when it is in draft mode."' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: You may only send a campaign when it is in draft mode. + '404': + description: '"": "not found"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: not found + summary: '' security: - - {} - /whitelabel/domains/subuser: + - Authorization: [] + /user/webhooks/parse/stats: parameters: [] - delete: - responses: - '204': - description: '' - parameters: [] - consumes: - - application/json - produces: [] - operationId: Disassociate a domain whitelabel from a given user. - summary: |- - Domain Whitelabels can be associated with subusers via parent accounts. This functionality allows - subusers to send mail + get: description: |- - **This endpoint allows you to disassociate a specific whitelabel from a subuser.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to retrieve the statistics for your Parse Webhook useage.** - Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments. - ## URI Parameters - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - | username | string | required | Username for the subuser to find associated whitelabels for. | - security: - - {} - get: + There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries). + operationId: Retrieves Inbound Parse Webhook statistics. + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of statistics to return on each page. + required: false + type: string + - name: offset + in: query + description: The number of statistics to skip. + required: false + type: string + - name: aggregated_by + in: query + description: 'How you would like the statistics to by grouped. ' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + required: false + type: string responses: '200': description: '' schema: - $ref: '#/definitions/whitelabel:domain_spf' + type: array + items: + type: object + properties: + date: + type: string + description: The date that the stats were collected. + stats: + type: array + description: The Parse Webhook usage statistics. + items: + type: object + properties: + metrics: + type: object + properties: + received: + type: number + description: The number of emails received and parsed by the Parse Webhook. + required: + - received + required: + - date + - stats examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: mail@example.com - user_id: 7 - ips: [] - custom_spf: true - default: false - legacy: false - automatic_security: false - valid: false - dns: - mail_server: - host: mail.example.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: mail.example.com - type: txt - data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' - valid: false - domain_spf: - host: example.com - type: txt - data: 'v=spf1 include:mail.example.com -all' - valid: false - dkim: - host: s1._domainkey.example.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: List the domain whitelabel associated with the given user. + - date: '2015-10-11' + stats: + - metrics: + received: 0 + - date: '2015-10-12' + stats: + - metrics: + received: 0 + - date: '2015-10-13' + stats: + - metrics: + received: 0 + - date: '2015-10-14' + stats: + - metrics: + received: 0 + - date: '2015-10-15' + stats: + - metrics: + received: 0 + - date: '2015-10-16' + stats: + - metrics: + received: 0 + - date: '2015-10-17' + stats: + - metrics: + received: 0 + - date: '2015-10-18' + stats: + - metrics: + received: 0 + - date: '2015-10-19' + stats: + - metrics: + received: 0 + - date: '2015-10-20' + stats: + - metrics: + received: 0 + - date: '2015-10-21' + stats: + - metrics: + received: 0 + - date: '2015-10-22' + stats: + - metrics: + received: 0 + - date: '2015-10-23' + stats: + - metrics: + received: 0 + - date: '2015-10-24' + stats: + - metrics: + received: 0 + - date: '2015-10-25' + stats: + - metrics: + received: 0 + - date: '2015-10-26' + stats: + - metrics: + received: 0 + - date: '2015-10-27' + stats: + - metrics: + received: 0 + - date: '2015-10-28' + stats: + - metrics: + received: 0 + - date: '2015-10-29' + stats: + - metrics: + received: 0 + - date: '2015-10-30' + stats: + - metrics: + received: 0 + - date: '2015-10-31' + stats: + - metrics: + received: 0 + - date: '2015-11-01' + stats: + - metrics: + received: 0 + - date: '2015-11-02' + stats: + - metrics: + received: 0 + - date: '2015-11-03' + stats: + - metrics: + received: 0 + - date: '2015-11-04' + stats: + - metrics: + received: 0 + - date: '2015-11-05' + stats: + - metrics: + received: 0 + - date: '2015-11-06' + stats: + - metrics: + received: 0 + - date: '2015-11-07' + stats: + - metrics: + received: 0 + - date: '2015-11-08' + stats: + - metrics: + received: 0 + - date: '2015-11-09' + stats: + - metrics: + received: 0 + - date: '2015-11-10' + stats: + - metrics: + received: 0 summary: '' + security: + - Authorization: [] + '/clients/{client_type}/stats': + parameters: + - name: client_type + in: path + description: 'Specifies the type of client to retrieve stats for. Must be either "phone", "tablet", "webmail", or "desktop".' + required: true + type: string + enum: + - phone + - tablet + - webmail + - desktop + get: description: |- - **This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.** + **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + ## Available Client Types + - phone + - tablet + - webmail + - desktop - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | username | string | Username of the subuser to find associated whitelabels for. | - security: - - {} - '/campaigns/{campaign_id}/schedules/now': - parameters: [] - post: + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: Retrieve stats by a specific client type. + consumes: + - application/json + produces: + - application/json + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: - '201': - description: '' - schema: - title: Send a Campaign response - type: object - properties: - id: - type: integer - format: int64 - status: - type: string - required: - - id - - status - examples: - application/json: - id: 1234 - status: Scheduled - '400': - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: subject - message: "subject can't be blank" - - field: sender_id - message: "sender_id can't be blank" - - field: plain_content - message: "plain_content can't be blank, please provide plain text or html content" - - field: list_id - message: You must select at least 1 segment or 1 list to send to. - - field: unsubscribe_tag - message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' - - field: suppression_group_id - message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '"": "You may only send a campaign when it is in draft mode."' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: You may only send a campaign when it is in draft mode. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - errors: - - field: null - message: not found - parameters: - - type: number - description: The id of the campaign - name: campaign_id - in: query - required: true + - date: '2014-10-01' + stats: + - metrics: + opens: 1 + unique_opens: 1 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: + opens: 0 + unique_opens: 0 + name: Gmail + type: client + summary: Gets email statistics by a single client type. + security: + - Authorization: [] + /browsers/stats: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your email statistics segmented by browser type.** + + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: 'Retrieve email statistics by browser. ' consumes: - application/json produces: - application/json - operationId: Send a Campaign - summary: '' - description: |- - Send your campaign right now. Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, we don't need a body. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - security: - - {} - /contactdb/custom_fields: - parameters: [] - post: + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string + - name: limit + in: query + description: The number of results to include on each page. + required: false + type: string + - name: offset + in: query + description: The number of results to exclude. + required: false + type: string + - name: aggregated_by + in: query + description: 'How to group the stats. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: browsers + in: query + description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times. + required: false + type: string responses: - '201': + '200': description: '' schema: - type: object - properties: - id: - type: integer - name: - type: string - type: - type: string - examples: - application/json: - id: 1 - name: pet - type: text - '400': - description: |- - "" : "Returned if request body is invalid JSON" - "type" : "Returned if custom field type is invalid or not provided" - "name" : "Returned if custom field name is not provided" + type: array + items: + $ref: '#/definitions/advanced_stats_clicks' examples: application/json: - errors: - - field: null - message: Returned if request body is invalid JSON - - field: type - message: Returned if custom field type is invalid or not provided - - field: name - message: Returned if custom field name is not provided - parameters: - - type: string - name: name - in: formData - description: '' - - type: string - name: type - in: formData - description: '' + - date: '2014-10-01' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser + - date: '2014-10-02' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser + summary: '' + security: + - Authorization: [] + /subusers/stats/sums: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** + + + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: ' Retrieve the totals for each email statistic metric for all subusers.' consumes: - application/json produces: - application/json - operationId: Create a Custom Field - summary: '' - description: |- - Create a custom field. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - get: + parameters: + - name: sort_by_direction + in: query + description: 'The direction you want to sort. ' + required: false + type: string + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: limit + in: query + description: Limits the number of results returned per page. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results from. + required: false + type: integer + - name: aggregated_by + in: query + description: How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string responses: '200': description: '' schema: - title: List All Custom Fields response - type: object - properties: - custom_fields: - type: array - items: - $ref: '#/definitions/contactdb_custom_field_with_id' - required: - - custom_fields - examples: - application/json: - lists: - - id: 1 - name: the jones - recipient_count: 1 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/category_stats' examples: application/json: - errors: - - field: null - message: authorization required - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: List All Custom Fields + date: '2015-10-11' + stats: [] summary: '' - description: "Get all custom fields. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." security: - - {} - '/contactdb/custom_fields/{custom_field_id}': + - Authorization: [] + /subusers/stats: parameters: [] get: + description: |- + **This endpoint allows you to retrieve the email statistics for the given subusers.** + + You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser. + + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: Retrieve email statistics for your subusers. + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: Limits the number of results returned per page. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results from. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: subusers + in: query + description: The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers. + required: true + type: string + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_custom_field_with_id' - examples: - application/json: - id: 1 - name: pet - type: text - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: invalid id - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"custom_field_id" : "Returned if custom_field_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/stats' examples: application/json: - errors: - - message: Custom field ID does not exist - parameters: - - type: number - description: The ID of the custom field you would like to retrieve - name: custom_field_id - in: query - required: true - consumes: - - application/json - produces: - - application/json - operationId: Get a Custom Field + - date: '2015-10-01' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-02' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-03' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-04' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-05' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-06' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-07' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-08' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-09' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-10' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 summary: '' + security: + - Authorization: [] + '/whitelabel/links/{id}/validate': + parameters: + - name: id + in: path + description: The id of the link whitelabel that you want to validate. + required: true + type: integer + post: description: |- - Get a custom field by ID. + **This endpoint allows you to validate a link whitelabel.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - delete: - responses: - '202': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - message: Custom Field delete is processing. - '400': - description: '"id" : "Returned if custom_field_id is not valid"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: Custom field in use by one or more segment conditions - - message: Custom field ID does not exist - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"custom_field_id" : "Returned if custom_field_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: Custom field ID does not exist - parameters: [] + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: Validate a Link Whitelabel consumes: - application/json produces: - application/json - operationId: Delete a Custom Field - summary: '' - description: |- - Delete a custom field by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - '/contactdb/lists/{list_id}': - parameters: [] - get: + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_list' + type: object + properties: + id: + type: integer + description: The id of the link whitelabel. + valid: + type: boolean + description: Indicates if the link whitelabel is valid. + enum: + - true + - false + validation_results: + type: object + description: The individual validations results for each of the DNS records associated with this link whitelabel. + required: + - domain_cname + properties: + domain_cname: + type: object + description: The DNS record generated for the sending domain used for this link whitelabel. + required: + - valid + - reason + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + enum: + - true + - false + reason: + type: + - string + - 'null' + description: 'Null if the DNS record is valid. If the DNS record is invalid, this will explain why.' + owner_cname: + type: object + description: The DNS record created to verify the link whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + enum: + - true + - false + reason: + type: + - 'null' + - string + description: 'Null if valid. If the DNS record is invalid, this will explain why.' + required: + - valid + - reason + required: + - id + - valid + - validation_results examples: application/json: id: 1 - name: listname - recipient_count: 0 + valid: true + validation_results: + domain_cname: + valid: false + reason: 'Expected CNAME to match "sendgrid.net." but found "example.com.".' + owner_cname: + valid: true + reason: null '400': - description: '"list_id" : "Returned if list_id is not valid"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: invalid id - '401': + description: Unexpected error in API call. See HTTP response body for details. + '500': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: + type: object + properties: errors: - - field: null - message: authorization required - '404': - description: '"list_id" : "Returned if list_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + description: The reasons why the validation failed. + items: + type: object + properties: + message: + type: string + description: The reason why the link whitelabel could not be validated. + required: + - message + required: + - errors examples: application/json: errors: - - field: null - message: List ID does not exist - parameters: - - type: number - description: The ID of the list to retrieve. - name: list_id - in: query - consumes: - - application/json - produces: - - application/json - operationId: Get a single list. + - message: internal error getting CNAME summary: '' - description: "Get a single list. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." security: - - {} - patch: + - Authorization: [] + '/ips/pools/{pool_name}/ips/{ip}': + parameters: + - name: pool_name + in: path + required: true + type: string + - name: ip + in: path + required: true + type: string + delete: + description: '' + operationId: Remove an IP address from a pool. + consumes: + - application/json + produces: [] + parameters: [] responses: - '200': + '204': description: '' schema: type: object properties: {} - '400': - description: |- - "name" : "Returned if list name is a duplicate of existing list or segment" - "name" : "Returned if list name is invalid or not provided" - "list_id" : "Returned if list_id is not valid" - "" : "Returned if request body is invalid JSON" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: invalid id - '404': - description: '"list_id" : "Returned if list_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: List ID does not exist - parameters: - - type: number - description: The ID of the list you are updating. - name: list_id - in: query - required: true - - type: string - name: name - in: formData - required: true - description: 'The new name for your list. ' + summary: '' + security: + - Authorization: [] + '/ips/{ip_address}': + parameters: + - name: ip_address + in: path + required: true + type: string + get: + description: '' + operationId: See which pools an IP address belongs to. consumes: - application/json produces: - application/json - operationId: Update a List - summary: '' - description: |- - Update the name of a list. - - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - delete: + parameters: [] responses: - '202': - description: '' - schema: - type: 'null' - '400': - description: |- - "list_id" : "Returned if list_id is not valid" - "delete_contacts" : "Returned if delete_contacts is not valid" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: delete_contacts - message: delete_contacts not a bool - - field: list_id - message: Returned if list_id is not valid - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"list_id" : "Returned if list_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + ip: + type: string + subusers: + type: array + items: + type: string + rdns: + type: string + pools: + type: array + items: + type: string + warmup: + type: boolean + start_date: + type: + - integer + - 'null' + whitelabeled: + type: boolean examples: application/json: - errors: - - message: 'List not found: 5' - parameters: - - type: boolean - description: Adds the ability to delete all contacts on the list in addition to deleting the list. - enum: - - true - - false - name: delete_contacts - in: query + ip: 000.00.00.0 + subusers: + - subuser1 + - subuser2 + rdns: o1.em.example.com + pools: + - test1 + warmup: false + start_date: null + whitelabeled: true + summary: '' + security: + - Authorization: [] + '/ips/pools/{pool_name}/ips': + parameters: + - name: pool_name + in: path + required: true + type: string + post: + description: '' + operationId: Add an IP to a pool consumes: - application/json produces: - application/json - operationId: Delete a List + parameters: + - name: body + in: body + schema: + type: object + properties: + ip: + type: string + responses: + '201': + description: '' + schema: + type: object + properties: + ip: + type: string + pools: + type: array + items: + type: string + start_date: + type: integer + warmup: + type: boolean + examples: + application/json: + ip: 000.00.00.0 + pools: + - test1 + start_date: 1409616000 + warmup: true summary: '' - description: |- - Delete a list by ID. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). security: - - {} - /contactdb/recipients/search: + - Authorization: [] + /api_key: parameters: [] - get: + post: + description: |- + This will create a new random API Key for the user. A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. + + There is a limit of 100 API Keys on your account. + + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. + operationId: Create API keys + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name you will use to describe this API Key. + scopes: + type: array + description: The individual permissions that you are giving to this API Key. + items: + type: string + required: + - name responses: - '200': + '201': description: '' schema: type: object properties: - recipients: + result: type: array items: - $ref: '#/definitions/contactdb_recipient' + $ref: '#/definitions/api_key_name_id_scopes' examples: application/json: - recipients: - - created_at: 1422313607 - email: jones@example.com - first_name: null - id: YUBh - last_clicked: null - last_emailed: null - last_name: Jones - last_opened: null - updated_at: 1422313790 - custom_fields: - - id: 23 - name: pet - value: Fluffy - type: text + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id '400': - description: |- - "" : "Returned if no search params are specified" - "field" : "Returned if the provided field is invalid or does not exist" + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]' - - message: No search params are specified + - field: name + message: missing required argument '401': description: '' schema: @@ -9547,769 +9992,803 @@ paths: errors: - field: null message: authorization required - parameters: - - type: string - name: '{field_name}' - in: query + '403': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: Cannot create more than 100 API Keys + summary: |- + **Generate a new API Key for the authenticated user** + + This will create a new random API Key for the user. A JSON reques + security: + - Authorization: [] + /categories/stats: + parameters: [] + get: + description: "**This endpoint allows you to retrieve all of your email statistics for each of your categories.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). " + operationId: Retrieve Email Statistics for Categories consumes: - application/json produces: - application/json - operationId: Get Recipients Matching Search Criteria - summary: |- - {% info %} - "field_name"* is a variable that is substituted for your actual custom field name from your recipient. - Text f - description: |- - Search the recipients in your contactdb. - - field_name: - - * is a variable that is substituted for your actual custom field name from your recipient. - * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) - * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert - your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to - Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through - Mon, 02 Feb 2015 23:59:59 GMT. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: categories + in: query + description: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. + required: true + type: string + - name: limit + in: query + description: The number of results to include. + required: false + type: integer + maximum: 500 + - name: offset + in: query + description: The number of results to skip. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/category_stats' + examples: + application/json: + - date: '2015-10-01' + stats: + - type: category + name: docs + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - type: category + name: mattscategory + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-01' + stats: + - type: category + name: docs + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - type: category + name: mattscategory + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + summary: '' security: - - {} - '/contactdb/recipients/{recipient_id}/lists': + - Authorization: [] + /stats: parameters: [] get: - responses: - '200': - description: '' - schema: - type: object - properties: - lists: - type: array - items: - $ref: '#/definitions/contactdb_list' - examples: - application/json: - lists: - - id: 1234 - name: Example list - recipient_count: 42 - '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: recipient ID is invalid - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"recipient_id" : "Returned if record for the recipient id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: recipient id not found - parameters: - - type: string - description: The ID of the recipient you are requesting lists for. - name: recipient_id - in: query - required: true + description: |- + **This endpoint allows you to retrieve all of your global email statistics between a given date range.** + + Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. + operationId: Retrieve global email statistics consumes: - application/json produces: - application/json - operationId: Get the Lists the Recipient Is On - summary: '' - description: |- - Each recipient can be on many lists. This endpoint gives you the lists this recipient is associated to. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - /contactdb/segments: - parameters: [] - post: + parameters: + - name: limit + in: query + description: The number of results to return. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_segments_with_id' - examples: - application/json: - id: 1 - name: Last Name Miller - list_id: 4 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - - field: last_clicked - value: 01/02/2015 - operator: gt - and_or: and - - field: clicks.campaign_identifier - value: '513' - operator: eq - and_or: or - recipient_count: 0 - '400': - description: |- - "name" : "Returned if the name is not valid" - "list_id" : "Returned if the list_id is not valid" - "and_or" : "Returned if and_or and set value is not passed into the request body" - "and_or" : "Returned if and_or is set on the only condition passed" - "and_or" : "Returned if and_or is set on all conditions" - "and_or" : "Returned if and_or is not set on more than one condition and less than all conditions" - "operator" : "Returned if operator and set value is not passed into the request body" - "value" : "Returned if value and set value is not passed into the request body" - "field" : "Returned if field and set value is not passed into the request body" - "" : "Returned if request body is not valid json" - "" : "Returned if invalid value is passed into one of the request body parameters" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: request body is not valid json - - message: invalid value is passed into one of the request body parameters - - field: field - message: field and set value is not passed into the request body - - field: value - message: value and set value is not passed into the request body - - field: operator - message: operator and set value is not passed into the request body - - field: and_or - message: and_or is not set on more than one condition and less than all conditions - - field: and_or - message: and_or is set on all conditions - - field: and_or - message: and_or is set on the only condition passed - - field: and_or - message: and_or and set value is not passed into the request body - - field: list_id - message: the list_id is not valid - - field: name - message: the name is not valid - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + type: object + properties: + date: + type: string + description: The date the stats were gathered. + stats: + type: array + description: The individual email activity stats. + items: + type: object + properties: + metrics: + type: object + properties: + blocks: + type: integer + description: The number of emails that were not allowed to be delivered by ISPs. + bounce_drops: + type: integer + description: The number of emails that were dropped because of a bounce. + bounces: + type: integer + description: The number of emails that bounced instead of being delivered. + clicks: + type: integer + description: The number of links that were clicked in your emails. + deferred: + type: integer + description: 'The number of emails that temporarily could not be delivered. ' + delivered: + type: integer + description: The number of emails SendGrid was able to confirm were actually delivered to a recipient. + invalid_emails: + type: integer + description: The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid. + opens: + type: integer + description: The total number of times your emails were opened by recipients. + processed: + type: integer + description: 'Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed.' + requests: + type: integer + description: The number of emails that were requested to be delivered. + spam_report_drops: + type: integer + description: The number of emails that were dropped due to a recipient previously marking your emails as spam. + spam_reports: + type: integer + description: The number of recipients who marked your email as spam. + unique_clicks: + type: integer + description: The number of unique recipients who clicked links in your emails. + unique_opens: + type: integer + description: The number of unique recipients who opened your emails. + unsubscribe_drops: + type: integer + description: The number of emails dropped due to a recipient unsubscribing from your emails. + unsubscribes: + type: integer + description: The number of recipients who unsubscribed from your emails. + required: + - date + - stats examples: application/json: - errors: - - field: null - message: authorization required - parameters: [] + - date: '2015-11-03' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-04' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-05' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-06' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-07' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-08' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-09' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + summary: '' + security: + - Authorization: [] + /categories/stats/sums: + parameters: [] + get: + description: "**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). " + operationId: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' consumes: - application/json produces: - application/json - operationId: Create a Segment - summary: '' - description: "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. \n\nSegments may contain multiple condtions, joined by an \"and\" or \"or\" in the \"and_or\" field. The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)." - security: - - {} - get: + parameters: + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string + - name: sort_by_direction + in: query + description: The direction you want to sort. + required: false + type: string + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: limit + in: query + description: Limits the number of results returned. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: '200': description: '' schema: - title: List All Segments response type: object properties: - segments: - type: array - items: - $ref: '#/definitions/contactdb_segments' - required: - - segments - examples: - application/json: - segments: - - id: 1234 - name: Age segments < 25 - conditions: - - field: age - value: '25' - operator: lt - recipient_count: 8 - - id: 2345 - name: email address - gmail - conditions: - - field: email - value: '@gmail.com' - operator: contains - recipient_count: 0 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + '': + $ref: '#/definitions/category_stats' examples: application/json: - errors: - - field: null - message: authorization required - parameters: [] + date: '2015-01-01' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 20 + deferred: 0 + delivered: 20 + invalid_emails: 0 + opens: 20 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 20 + unique_opens: 20 + unsubscribe_drops: 0 + unsubscribes: 20 + name: cat1 + type: category + - metrics: + blocks: 1 + bounce_drops: 0 + bounces: 0 + clicks: 19 + deferred: 0 + delivered: 19 + invalid_emails: 0 + opens: 19 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 19 + unique_opens: 19 + unsubscribe_drops: 0 + unsubscribes: 19 + name: cat2 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 5 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 5 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 5 + name: cat3 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 6 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 6 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 6 + name: cat4 + type: category + - metrics: + blocks: 10 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 10 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: cat5 + type: category + summary: '' + security: + - Authorization: [] + /user/webhooks/event/settings: + parameters: [] + patch: + description: '' + operationId: Update Event Notification Settings consumes: - application/json produces: - application/json - operationId: List All Segments - summary: '' - description: |- - Get all your segments. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - security: - - {} - '/whitelabel/links/{link_id}/subuser': - parameters: [] - post: - responses: - '200': - description: '' + parameters: + - name: body + in: body schema: type: object properties: - id: - type: integer - domain: - type: string - subdomain: - type: string - username: + enabled: + type: boolean + url: type: string - user_id: - type: integer - default: + group_resubscribe: type: boolean - valid: + delivered: type: boolean - legacy: + group_unsubscribe: type: boolean - dns: - type: object - properties: - domain_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - owner_cname: - type: object - properties: - valid: - type: boolean - type: - type: string - host: - type: string - data: - type: string - examples: - application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - parameters: - - type: string - name: username - in: formData - description: '' - consumes: - - application/json - produces: - - application/json - operationId: Associate Link - summary: '' - description: '' - security: - - {} - /whitelabel/domains: - parameters: [] - post: - responses: - '201': - description: '' - schema: - $ref: '#/definitions/whitelabel::domain' - examples: - application/json: - id: 302183 - user_id: 1446226 - subdomain: example - domain: example.com - username: mbernier - ips: [] - custom_spf: false - default: true - legacy: false - automatic_security: true - valid: false - dns: - mail_cname: - valid: false - type: cname - host: example.example.com - data: u1446226.wl.sendgrid.net - dkim1: - valid: false - type: cname - host: s1._domainkey.example.com - data: s1.domainkey.u1446226.wl.sendgrid.net - dkim2: - valid: false - type: cname - host: s2._domainkey.example.com - data: s2.domainkey.u1446226.wl.sendgrid.net - parameters: - - type: string - name: domain - in: formData - required: true - description: Domain being whitelabeled. - - type: string - name: subdomain - in: formData - required: true - description: The subdomain to use for this domain whitelabel. - - type: string - name: username - in: formData - required: false - description: The username that this whitelabel will be associated with. - - type: string - name: ips - in: formData - required: false - description: The IP addresses that will be included in the custom SPF record for this whitelabel. - - type: string - name: custom_spf - in: formData - required: false - description: Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security. - - type: string - name: default - in: formData - required: false - description: "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain." - - type: string - name: automatic_security - in: formData - required: false - description: 'Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.' + spamreport: + type: boolean + bounce: + type: boolean + deferred: + type: boolean + unsubscribe: + type: boolean + processed: + type: boolean + open: + type: boolean + click: + type: boolean + dropped: + type: boolean + responses: + '200': + description: '' + schema: + type: object + properties: + enabled: + type: boolean + url: + type: string + group_resubscribe: + type: boolean + delivered: + type: boolean + group_unsubscribe: + type: boolean + spamreport: + type: boolean + bounce: + type: boolean + deferred: + type: boolean + unsubscribe: + type: boolean + processed: + type: boolean + open: + type: boolean + click: + type: boolean + dropped: + type: boolean + examples: + application/json: + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spamreport: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true + summary: '' + security: + - Authorization: [] + get: + description: '' + operationId: Retrieve Event Webhook Settings consumes: - application/json produces: - application/json - operationId: Create a domain whitelabel. - summary: |- - When creating a whitelabel for a subuser, there are two options available: - Use the "username" parameter. This allows - description: |- - **This endpoint allows you to create a whitelabel for one of your domains.** - - If you are creating a domain whitelabel that you would like a subuser to use, you have two options: - 1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. - 2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - security: - - {} - get: + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - id: - type: number - description: The ID of the domain whitelabel. - user_id: - type: number - description: The ID of the user that this whitelabel will be associated with. - subdomain: - type: string - description: The subdomain created for this domain whitelabel. - domain: - type: string - description: The domain that this whitelabel was created for. - username: - type: string - description: The username that this whitelabel is associated with. - ips: - type: array - description: The IPs that will be included in the custom SPF record. - items: - type: string - custom_spf: - type: boolean - description: Indicates if this whitelabel has custom SPF. - default: - type: boolean - description: Indicates if this whitelabel has been set as the default whitelabel. - legacy: - type: boolean - description: Indicates if this is whitelabel was created with the legacy whitelabel tool. - automatic_security: - type: boolean - description: Indicates if this whitelabel uses automated security. - valid: - type: boolean - description: Indicates if this is a valid whitelabel or not. - dns: - type: object - description: The DNS records for this whitelabel that are used for authenticating the sending domain. - properties: - mail_server: - type: object - description: Designates which mail server is responsible for accepting messages from a domain. - properties: - valid: - type: boolean - description: Indicates if this is a valid DNS record with no conflicts. - type: - type: string - description: The type of DNS record. - host: - type: string - description: The domain sending the messages. - data: - type: string - description: The mail server responsible for accepting messages. - subdomain_spf: - type: object - description: The SPF record for the subdomain used to create this whitelabel. - properties: - valid: - type: boolean - description: Indicates if the SPF record is valid. - type: - type: string - description: The type of data in the SPF record. - host: - type: string - description: The domain that this SPF record will be used to authenticate. - data: - type: string - description: The SPF record. - dkim: - type: object - description: The DNS record used when creating the DKIM signature. - properties: - valid: - type: boolean - description: Indicates if this DNS record is valid. - type: - type: string - description: The type of DNS record. - enum: - - cname - - mx - - txt - host: - type: string - description: The domain that these DNS records will be applied to. - format: hostname - data: - type: string - description: The DNS record. - required: - - id - - user_id - - subdomain - - domain - - username - - ips - - custom_spf - - default - - legacy - - automatic_security - - valid - - dns + type: object + properties: + enabled: + type: boolean + url: + type: string + group_resubscribe: + type: boolean + delivered: + type: boolean + group_unsubscribe: + type: boolean + spam_report: + type: boolean + bounce: + type: boolean + deferred: + type: boolean + unsubscribe: + type: boolean + processed: + type: boolean + open: + type: boolean + click: + type: boolean + dropped: + type: boolean examples: application/json: - - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - ips: - - 192.168.1.1 - - 192.168.1.2 - custom_spf: true - default: true - legacy: false - automatic_security: true - valid: true - dns: - mail_cname: - host: mail.example.com - type: cname - data: u7.wl.sendgrid.net - valid: true - spf: - host: example.com - type: txt - data: 'v=spf1 include:u7.wl.sendgrid.net -all' - valid: true - dkim1: - host: s1._domainkey.example.com - type: cname - data: s1._domainkey.u7.wl.sendgrid.net - valid: true - dkim2: - host: s2._domainkey.example.com - type: cname - data: s2._domainkey.u7.wl.sendgrid.net - valid: true - - id: 2 - domain: example2.com - subdomain: news - username: jane@example2.com - user_id: 8 - ips: [] - custom_spf: false - default: true - legacy: false - automatic_security: true - valid: false - dns: - mail_server: - host: news.example2.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: news.example2.com - type: txt - data: 'v=spf1 include:sendgrid.net ~all' - valid: false - domain_spf: - host: example2.com - type: txt - data: 'v=spf1 include:news.example2.com -all' - valid: false - dkim: - host: example2.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false - parameters: - - type: integer - description: Number of domains to return. - name: limit - in: query - - type: integer - description: Paging offset. - name: offset - in: query - - type: boolean - description: Exclude subuser domains from the result. - name: exclude_subusers - in: query - - type: string - description: The username associated with a whitelabel. - name: username - in: query - - type: string - description: Search for domain whitelabels that match the given domain. - name: domain - in: query + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true + summary: '' + security: + - Authorization: [] + /user/webhooks/event/test: + parameters: [] + post: + description: '' + operationId: 'Test Event Notification Settings ' consumes: - application/json - produces: - - application/json - operationId: List all domain whitelabels. + produces: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + url: + type: string + responses: + '204': + description: '' + schema: + type: object + properties: {} summary: '' - description: | - **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) security: - - {} - '/whitelabel/domains/{id}/ips': + - Authorization: [] + /user/webhooks/parse/settings: parameters: [] - post: + get: + description: '' + operationId: Retrieve Parse API settings + consumes: + - application/json + produces: + - application/json + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/whitelabel:domain_spf' + type: object + properties: + result: + type: array + items: + type: object + properties: + hostname: + type: string + url: + type: string + spam_check: + type: boolean + send_raw: + type: boolean examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - ips: [] - custom_spf: true - default: false - legacy: false - automatic_security: false - valid: false - dns: - mail_server: - host: mail.example.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: mail.example.com - type: txt - data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' - valid: false - domain_spf: - host: example.com - type: txt - data: 'v=spf1 include:mail.example.com -all' - valid: false - dkim: - host: s1._domainkey.example.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false - parameters: - - type: string - name: ip - in: formData - required: true - description: IP to associate with the domain. Used for manually specifying IPs for custom SPF. - consumes: - - application/json - produces: - - application/json - operationId: Add an IP to a domain whitelabel. + result: + - hostname: example.com + url: 'http://example.com/example' + spam_check: false + send_raw: false summary: '' + security: + - Authorization: [] + '/whitelabel/ips/{id}/validate': + parameters: + - name: id + in: path + required: true + type: integer + post: description: |- - **This endpoint allows you to add an IP address to a domain whitelabel.** + **This endpoint allows you to validate an IP whitelabel.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | ID of the domain to which you are adding an IP | - security: - - {} - '/whitelabel/domains/{domain_id}/subuser': - parameters: [] - post: - responses: - '201': - description: '' - schema: - $ref: '#/definitions/whitelabel:domain_spf' - examples: - application/json: - id: 1 - domain: example.com - subdomain: mail - username: mail@example.com - user_id: 7 - ips: [] - custom_spf: true - default: false - legacy: false - automatic_security: false - valid: false - dns: - mail_server: - host: mail.example.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: mail.example.com - type: txt - data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' - valid: false - domain_spf: - host: example.com - type: txt - data: 'v=spf1 include:mail.example.com -all' - valid: false - dkim: - host: s1._domainkey.example.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false - parameters: - - type: string - name: username - in: formData - required: true - description: Username to associate with the domain whitelabel. + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: Validate an IP whitelabel consumes: - application/json produces: - application/json - operationId: Associate a domain whitelabel with a given user. - summary: '' - description: |- - **This endpoint allows you to associate a specific domain whitelabel with a subuser.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - - Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools. - - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | domain_id | integer | ID of the domain whitelabel to associate with the subuser. | - security: - - {} - '/templates/{template_id}/versions/{version_id}/activate': - parameters: [] - post: + parameters: [] responses: '200': description: '' @@ -10317,1721 +10796,466 @@ paths: type: object properties: id: - type: string - description: The ID of the template version. - updated_at: - type: string - description: The date and time that the version was last updated. - Transactional Template Version: - $ref: '#/definitions/transactional_templates::versions' + type: integer + description: The id of the IP whitelabel. + valid: + type: boolean + description: Indicates if the IP whitelabel is valid. + enum: + - true + - false + validation_results: + type: object + description: The specific results of the validation. + properties: + a_record: + type: object + properties: + valid: + type: boolean + description: Indicates if the IP whitelabel could be validated. + enum: + - true + - false + reason: + type: + - 'null' + - string + description: The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated. + required: + - valid + - reason required: - id - - updated_at + - valid + - validation_results examples: application/json: - id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 - template_id: e3a61852-1acb-4b32-a1bc-b44b3814ab78 - active: 1 - name: example_version_name - html_content: '<%body%>' - plain_content: '<%body%>' - subject: '<%subject%>' - updated_at: '2014-06-12 11:33:00' - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Activate a transactional template version. + id: 1 + valid: true + validation_results: + a_record: + valid: true + reason: null + '404': + description: Unexpected error in API call. See HTTP response body for details. + schema: + type: object + properties: + errors: + type: array + description: The error messages for the failed validation. + items: + type: object + properties: + message: + type: string + description: A message describing why the IP could not be validated. + required: + - message + required: + - errors + examples: + application/json: + errors: + - message: Whitelabel ip not found. + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The error messages for the failed validation. + items: + type: object + properties: + message: + type: string + description: A message describing why the IP whitelabel could not be validated. + required: + - message + required: + - errors + examples: + application/json: + errors: + - message: internal error getting rDNS summary: '' - description: |- - **This endpoint allows you to activate a version of one of your templates.** - - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - - - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | security: - - {} - '/whitelabel/domains/{id}/ips/{ip}': + - Authorization: [] + /tracking_settings/subscription: parameters: [] - delete: + patch: + description: |- + **This endpoint allows you to update your current settings for subscription tracking.** + + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Update Subscription Tracking Settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/subscription_tracking_settings' responses: '200': description: '' schema: - $ref: '#/definitions/whitelabel:domain_spf' + $ref: '#/definitions/subscription_tracking_settings' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: mail@example.com - user_id: 7 - ips: [] - custom_spf: true - default: false - legacy: false - automatic_security: false - valid: false - dns: - mail_server: - host: mail.example.com - type: mx - data: sendgrid.net - valid: false - subdomain_spf: - host: mail.example.com - type: txt - data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' - valid: false - domain_spf: - host: example.com - type: txt - data: 'v=spf1 include:mail.example.com -all' - valid: false - dkim: - host: s1._domainkey.example.com - type: txt - data: k=rsa; t=s; p=publicKey - valid: false - parameters: [] - consumes: - - application/json - produces: - - application/json - operationId: Remove an IP from a domain whitelabel. + enabled: true + landing: landing page html + url: url + replace: replacement tag + html_content: html content + plain_content: text content summary: '' + security: + - Authorization: [] + get: description: |- - **This endpoint allows you to remove a domain's IP address from that domain's whitelabel.** + **This endpoint allows you to retrieve your current settings for subscription tracking.** - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer | ID of the domain whitelabel to delete the IP from. | - | ip | string | IP to remove from the domain whitelabel. | - security: - - {} - /whitelabel/domains/default: - parameters: [] - get: - responses: - '200': - description: '' - schema: - $ref: '#/definitions/whitelabel:domain_spf' - parameters: [] + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Retrieve Subscription Tracking Settings consumes: - application/json produces: - application/json - operationId: Get the default domain whitelabel. + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/subscription_tracking_settings' + examples: + application/json: + enabled: true + html_content: | +

Something something unsubscribe <% %> something something

+ landing: | +

subscribehere

+ plain_content: 'Something something unsubscribe <% %> something something' + replace: thetag + url: '' summary: '' + security: + - Authorization: [] + /tracking_settings: + parameters: [] + get: description: |- - **This endpoint allows you to retrieve the default whitelabel for a domain.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | domain | string |The domain to find a default domain whitelabel for. | - security: - - {} - '/templates/{template_id}/versions': - parameters: [] - post: + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Retrieve Tracking Settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: The number of settings to return. + type: integer + - name: offset + in: query + description: Where in the list of results you want to begin retrieving settings. + type: integer responses: - '201': + '200': description: '' schema: type: object properties: - id: - type: string - description: The id of the new transactional template version. - updated_at: - type: string - description: The date and time that this transactional template version was updated. - Transactional Template Version: - $ref: '#/definitions/transactional_templates::versions' - required: - - id - - updated_at + result: + type: array + description: The list of all tracking settings. + items: + type: object + properties: + name: + type: string + description: The name of the event being tracked. + title: + type: string + description: The title of the tracking setting. + description: + type: string + description: A description about the event that is being tracked. + enabled: + type: boolean + description: Indicates if this tracking setting is currently enabled. examples: application/json: - id: 8aefe0ee-f12b-4575-b5b7-c97e21cb36f3 - template_id: ddb96bbc-9b92-425e-8979-99464621b543 - active: 1 - name: example_version_name - html_content: '<%body%>' - plain_content: '<%body%>' - subject: '<%subject%>' - updated_at: '2014-03-19 18:56:33' - parameters: [] + result: + - name: open + title: Open Tracking + description: lorem ipsum... . + enabled: true + summary: '' + security: + - Authorization: [] + /tracking_settings/google_analytics: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your current setting for Google Analytics.** + + For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). + + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Retrieve Google Analytics Settings consumes: - application/json produces: - application/json - operationId: Create a new transactional template version. + parameters: [] + responses: + '200': + description: '' + schema: + $ref: '#/definitions/google_analytics_settings' + examples: + application/json: + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' summary: '' - description: | - **This endpoint allows you to create a new version of a template.** + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update your current setting for Google Analytics.** - Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - security: - - {} - /: - parameters: [] - get: + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Update Google Analytics Settings + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/google_analytics_settings' responses: '200': description: '' schema: - type: object - properties: - current_user_url: - type: string - current_user_authorizations_html_url: - type: string - authorizations_url: - type: string - code_search_url: - type: string - emails_url: - type: string - emojis_url: - type: string - events_url: - type: string - feeds_url: - type: string - followers_url: - type: string - following_url: - type: string - gists_url: - type: string - hub_url: - type: string - issue_search_url: - type: string - issues_url: - type: string - keys_url: - type: string - notifications_url: - type: string - organization_repositories_url: - type: string - organization_url: - type: string - public_gists_url: - type: string - rate_limit_url: - type: string - repository_url: - type: string - repository_search_url: - type: string - current_user_repositories_url: - type: string - starred_url: - type: string - starred_gists_url: - type: string - team_url: - type: string - user_url: - type: string - user_organizations_url: - type: string - user_repositories_url: - type: string - user_search_url: - type: string + $ref: '#/definitions/google_analytics_settings' examples: application/json: - current_user_url: 'https://api.github.com/user' - current_user_authorizations_html_url: 'https://github.com/settings/connections/applications{/client_id}' - authorizations_url: 'https://api.github.com/authorizations' - code_search_url: 'https://api.github.com/search/code?q={query}{&page,per_page,sort,order}' - emails_url: 'https://api.github.com/user/emails' - emojis_url: 'https://api.github.com/emojis' - events_url: 'https://api.github.com/events' - feeds_url: 'https://api.github.com/feeds' - followers_url: 'https://api.github.com/user/followers' - following_url: 'https://api.github.com/user/following{/target}' - gists_url: 'https://api.github.com/gists{/gist_id}' - hub_url: 'https://api.github.com/hub' - issue_search_url: 'https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}' - issues_url: 'https://api.github.com/issues' - keys_url: 'https://api.github.com/user/keys' - notifications_url: 'https://api.github.com/notifications' - organization_repositories_url: 'https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}' - organization_url: 'https://api.github.com/orgs/{org}' - public_gists_url: 'https://api.github.com/gists/public' - rate_limit_url: 'https://api.github.com/rate_limit' - repository_url: 'https://api.github.com/repos/{owner}/{repo}' - repository_search_url: 'https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}' - current_user_repositories_url: 'https://api.github.com/user/repos{?type,page,per_page,sort}' - starred_url: 'https://api.github.com/user/starred{/owner}{/repo}' - starred_gists_url: 'https://api.github.com/gists/starred' - team_url: 'https://api.github.com/teams' - user_url: 'https://api.github.com/users/{user}' - user_organizations_url: 'https://api.github.com/user/orgs' - user_repositories_url: 'https://api.github.com/users/{user}/repos{?type,page,per_page,sort}' - user_search_url: 'https://api.github.com/search/users?q={query}{&page,per_page,sort,order}' - parameters: - - type: string - name: X-Forwarded-For - in: header - description: '' - - type: integer - name: X-Request-Start - in: header - description: '' - - type: string - name: From - in: header - description: '' - - type: integer - name: Total-Route-Time - in: header - description: '' - - type: string - name: X-Request-Id - in: header - description: '' - - type: string - name: X-Forwarded-Proto - in: header - description: '' - - type: string - name: Via - in: header - description: '' - - type: integer - name: Connect-Time - in: header - description: '' - - type: string - name: Accept - in: header - description: '' - - type: integer - name: X-Forwarded-Port - in: header - description: '' + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' + summary: '' + security: + - Authorization: [] + /tracking_settings/open: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve your current settings for open tracking.** + + Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Get Open Tracking Settings consumes: - application/json produces: - application/json - operationId: '' - summary: '' - description: '' - /robots.txt: - parameters: [] - get: + parameters: [] responses: '200': description: '' schema: type: object - properties: {} + properties: + enabled: + type: boolean + description: Indicates if open tracking is enabled. + required: + - enabled examples: - text/plain: |- - # If you would like to crawl GitHub contact us at support@github.com. - # We also provide an extensive API: https://developer.github.com/ - - User-agent: CCBot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: coccoc - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: dotbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: duckduckbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: EtaoSpider - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Googlebot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: HTTrack - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: ia_archiver - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: IntuitGSACrawler - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Mail.RU_Bot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: msnbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Bingbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: naverbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: red-app-gsa-p-one - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: rogerbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: SandDollar - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: seznambot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Slurp - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Swiftbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Telefonica - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: teoma - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Twitterbot - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - User-agent: Yandex - Allow: /*/*/tree/master - Allow: /*/*/blob/master - Disallow: /ekansa/Open-Context-Data - Disallow: /ekansa/opencontext-* - Disallow: /*/*/pulse - Disallow: /*/*/tree/* - Disallow: /*/*/blob/* - Disallow: /*/*/wiki/*/* - Disallow: /gist/*/*/* - Disallow: /oembed - Disallow: /*/forks - Disallow: /*/stars - Disallow: /*/download - Disallow: /*/revisions - Disallow: /*/*/issues/new - Disallow: /*/*/issues/search - Disallow: /*/*/commits/*/* - Disallow: /*/*/commits/*?author - Disallow: /*/*/commits/*?path - Disallow: /*/*/branches - Disallow: /*/*/tags - Disallow: /*/*/contributors - Disallow: /*/*/comments - Disallow: /*/*/stargazers - Disallow: /*/*/search - Disallow: /*/tarball/ - Disallow: /*/zipball/ - Disallow: /*/*/archive/ - Disallow: /raw/* - Disallow: /*/followers - Disallow: /*/following - Disallow: /stars/* - Disallow: /*/blame/ - Disallow: /*/watchers - Disallow: /*/network - Disallow: /*/graphs - Disallow: /*/raw/ - Disallow: /*/compare/ - Disallow: /*/cache/ - Disallow: /*/*/blame/ - Disallow: /*/*/watchers - Disallow: /*/*/network - Disallow: /*/*/graphs - Disallow: /*/*/raw/ - Disallow: /*/*/compare/ - Disallow: /*/*/cache/ - Disallow: /.git/ - Disallow: /*/.git/ - Disallow: /*.git$ - Disallow: /*/sitemap.xml - Disallow: /search/advanced - Disallow: /search - Disallow: /*q= - Disallow: /*.atom - Disallow: /login - - - User-agent: * - Allow: /humans.txt - Disallow: / + application/json: + enabled: true + summary: '' + security: + - Authorization: [] + patch: + description: |- + **This endpoint allows you to update your current settings for open tracking.** + + Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: Update Open Tracking Settings + consumes: + - application/json + produces: + - application/json parameters: - - type: integer - name: X-Forwarded-Port - in: header - description: '' - - type: string - name: Via - in: header - description: '' - - type: string - name: From - in: header - description: '' - - type: string - name: X-Request-Id - in: header - description: '' - - type: string - name: X-Forwarded-For - in: header - description: '' - - type: integer - name: X-Request-Start - in: header - description: '' - - type: integer - name: Total-Route-Time - in: header - description: '' - - type: string - name: X-Forwarded-Proto - in: header - description: '' - - type: integer - name: Connect-Time - in: header + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: The new status that you want to set for open tracking. + responses: + '200': description: '' + schema: + type: object + properties: + enabled: + type: boolean + description: Indicates if open tracking is enabled. + required: + - enabled + examples: + application/json: + enabled: true + summary: '' + security: + - Authorization: [] + /mail_settings: + parameters: [] + get: + description: |- + **This endpoint allows you to retrieve a list of all mail settings.** + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: Retrieve all mail settings consumes: - application/json produces: - - text/plain - operationId: '' + - application/json + parameters: + - name: limit + in: query + description: The number of settings to return. + type: integer + - name: offset + in: query + description: Where in the list of results to begin displaying settings. + type: integer + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + description: The list of all mail settings. + items: + type: object + properties: + title: + type: string + description: The title of the mail setting. + enabled: + type: boolean + description: Indicates if this mail setting is currently enabled. + name: + type: string + description: The name of the mail setting. + description: + type: string + description: A description of the mail setting. + required: + - title + - enabled + - name + - description + required: + - result + examples: + application/json: + result: + - title: Address Whitelist + enabled: false + name: address_whitelist + description: Address / domains that should never have email suppressed. + - title: BCC + enabled: false + name: bcc + description: Automatically BCC an address for every e-mail sent. + - title: Bounce Purge + enabled: false + name: bounce_purge + description: Allows you to automatically purge bounce records from SendGrid after a specified number of days. + - title: Event Notification + enabled: true + name: event_notify + description: 'Controls notifications for events, such as bounces, clicks, and opens.' + - title: Footer + enabled: false + name: footer + description: Allows you to add a custom footer to outgoing email. + - title: Forward Bounce + enabled: true + name: forward_bounce + description: Allows you to forward bounces to a specific email address. + - title: Forward Spam + enabled: false + name: forward_spam + description: Allows for a copy of spam reports to be forwarded to an email address. + - title: Legacy Email Template + enabled: true + name: template + description: Allows you to customize your outgoing HTML emails. + - title: Plain Content + enabled: false + name: plain_content + description: Convert your plain text emails to HTML. + - title: Spam Checker + enabled: true + name: spam_check + description: Check outbound messages for spam content. summary: '' - description: '' + security: + - Authorization: [] definitions: - user_scheduled_send_status: - allOf: - - $ref: '#/definitions/mail_batch_id' - - type: object - description: The status of the scheduled send. - properties: - status: - type: string - description: The status of the scheduled send. - enum: - - cancel - - pause - required: - - status contacts: type: object properties: @@ -12056,15 +11280,6 @@ definitions: type: string zip: type: string - mail_settings_footer: - type: object - properties: - enabled: - type: boolean - html_content: - type: string - plain_content: - type: string subuser: title: List all Subusers for a parent response type: object @@ -12087,17 +11302,6 @@ definitions: - id - username - email - stats: - type: object - properties: {} - contactdb_recipient_count: - type: object - properties: - recipient_count: - type: number - description: The count of recipients. - required: - - recipient_count contactdb_segments_conditions: type: object properties: @@ -12149,6 +11353,27 @@ definitions: - username - user_id - email + contactdb_segments: + title: Create a Segment request + type: object + properties: + name: + type: string + description: The name of this segment. + list_id: + type: integer + description: The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list. + conditions: + type: array + description: The conditions for a recipient to be included in this segment. + items: + $ref: '#/definitions/contactdb_segments_conditions' + recipient_count: + type: number + description: The count of recipients in this list. This is not included on creation of segments. + required: + - name + - conditions campaign_request: type: object properties: @@ -12162,8 +11387,8 @@ definitions: description: The subject of your campaign that your recipients will see. sender_id: type: - - number - 'null' + - integer description: 'The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails.' list_ids: type: @@ -12171,14 +11396,14 @@ definitions: - 'null' description: The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs items: - type: number + type: integer segment_ids: type: - array - 'null' description: The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. items: - type: number + type: integer categories: type: - array @@ -12188,8 +11413,8 @@ definitions: type: string suppression_group_id: type: - - number - 'null' + - integer description: 'The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.' custom_unsubscribe_url: type: @@ -12213,40 +11438,6 @@ definitions: description: The plain text content of your emails. required: - title - contactdb_custom_field: - title: ContactDB Custom field schema. - type: object - properties: - name: - type: string - description: The name of the field - type: - type: string - description: The type of the field. - enum: - - date - - text - - number - contactdb_custom_field_with_id: - allOf: - - $ref: '#/definitions/contactdb_custom_field' - - type: object - properties: - id: - type: number - description: The ID of the custom field. - title: ContactDB Custom field schema with ID. - contactdb_custom_field_with_id_value: - allOf: - - $ref: '#/definitions/contactdb_custom_field_with_id' - - type: object - properties: - value: - type: - - string - - 'null' - description: "The value of this recipient's custom field" - title: ContactDB Custom field schema. contactdb_recipient_response: type: object properties: @@ -12281,47 +11472,16 @@ definitions: properties: message: type: string - error_indices: - type: array - items: - type: number - required: - - error_count - - new_count - - persisted_recipients - - updated_count - contactdb_segments: - title: Create a Segment request - type: object - properties: - name: - type: string - description: The name of this segment. - list_id: - type: integer - description: The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list. - conditions: - type: array - description: The conditions for a recipient to be included in this segment. - items: - $ref: '#/definitions/contactdb_segments_conditions' - recipient_count: - type: number - description: The count of recipients in this list. This is not included on creation of segments. + error_indices: + type: array + items: + type: number required: - - name - - conditions - contactdb_segments_with_id: - allOf: - - type: object - properties: - id: - type: number - description: The ID of the segment. - required: - - id - - $ref: '#/definitions/contactdb_segments' - 'transactional_templates::versions': + - error_count + - new_count + - persisted_recipients + - updated_count + transactional_template_version: type: object properties: template_id: @@ -12336,15 +11496,12 @@ definitions: name: type: string description: Name of the new transactional template version. - maxLength: 100 html_content: type: string description: 'The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content.' - maxLength: 0 plain_content: type: string description: 'Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content.' - maxLength: 0 subject: type: string description: 'Subject of the new transactional template version. Must include <%subject%> tag.' @@ -12365,33 +11522,6 @@ definitions: items: type: string - $ref: '#/definitions/api_key_name_id' - campaign_response: - allOf: - - $ref: '#/definitions/campaign_request' - - type: object - properties: - status: - type: string - description: The status of your campaign. - required: - - status - 'global:id': - type: integer - mail_batch_id: - type: object - properties: - batch_id: - type: string - pattern: "^[a-zA-Z0-9\\-\\_]" - required: - - batch_id - 'global:empty_request': - type: 'null' - downloads: - type: object - properties: - download_url: - type: string credentials: type: object properties: @@ -12406,74 +11536,203 @@ definitions: type: string username: type: string - mail_settings_address_whitelabel: + partner_settings_new_relic: type: object properties: + enable_subuser_statistics: + type: boolean + description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. enabled: type: boolean - list: - type: array - items: - type: string - mail_settings_bcc: + description: 'Indicates if this setting is enabled. ' + license_key: + type: string + description: The license key provided with your New Relic account. + required: + - enabled + - license_key + suppression_group_unsubscribes: + type: object + allOf: + - $ref: '#/definitions/suppression_group' + - type: object + required: + - unsubscribes + properties: + unsubscribes: + type: integer + description: The unsubscribes associated with this group. + mail_settings_forward_bounce: type: object properties: email: - type: string + type: + - string + - 'null' + description: The email address that you would like your bounce reports forwarded to. enabled: type: boolean - mail_settings_bounce_purge: + description: Indicates if the bounce forwarding mail setting is enabled. + api_key_name_id: type: object properties: - enabled: - type: boolean - soft_bounces: - type: - - integer - - 'null' - hard_bounces: - type: - - integer - - 'null' - 'mail_settings::patch': + api_key_id: + type: string + description: 'The ID of your API Key. ' + name: + type: string + description: The name of your API Key. + monitor: + title: Create monitor settings request + type: object + properties: + email: + type: string + description: The email address to send emails at the frequency specified for monitoring. + format: email + frequency: + type: number + description: 'The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. ' + required: + - email + - frequency + 'global:id': + type: integer + mail_settings_template: type: object properties: enabled: type: boolean + description: Indicates if the legacy email template setting is enabled. + html_content: + type: string + description: The HTML content that you want to use for your legacy email template. mail_settings_forward_spam: type: object properties: email: - type: - - string - - 'null' + type: string + description: The email address where you would like the spam reports to be forwarded. enabled: type: boolean - mail_settings_spam_check: + description: Indicates if the Forward Spam setting is enabled. + mail_settings_patch: type: object properties: enabled: type: boolean - max_score: - type: number - url: + description: Indicates if the mail setting is enabled. + email: type: string - mail_settings_template: + description: The email address of the recipient. + mail_settings_bcc: type: object properties: + email: + type: string + description: The email address that will be sent a blind carbon copy. enabled: type: boolean - html_content: - type: string - partner_settings_new_relic: + description: Indicates if the BCC setting is enabled. + mail_settings_address_whitelabel: type: object properties: - enable_subuser_statistics: - type: boolean enabled: type: boolean - license_key: + description: 'Indicates if you have an email address whitelist enabled. ' + list: + type: array + description: All email address that are currently on the whitelist. + items: + type: string + 'global:empty_request': + type: 'null' + mail_batch_id: + type: object + properties: + batch_id: + type: string + pattern: "^[a-zA-Z0-9\\-\\_]" + required: + - batch_id + campaign_response: + allOf: + - $ref: '#/definitions/campaign_request' + - type: object + properties: + status: + type: string + description: The status of your campaign. + id: + type: integer + required: + - status + contactdb_segments_with_id: + allOf: + - type: object + properties: + id: + type: number + description: The ID of the segment. + required: + - id + - $ref: '#/definitions/contactdb_segments' + contactdb_custom_field_with_id_value: + allOf: + - $ref: '#/definitions/contactdb_custom_field_with_id' + - type: object + properties: + value: + type: + - string + - 'null' + description: "The value of this recipient's custom field" + title: ContactDB Custom field schema. + contactdb_custom_field_with_id: + allOf: + - $ref: '#/definitions/contactdb_custom_field' + - type: object + properties: + id: + type: number + description: The ID of the custom field. + title: ContactDB Custom field schema with ID. + contactdb_custom_field: + title: ContactDB Custom field schema. + type: object + properties: + name: + type: string + description: The name of the field + type: type: string + description: The type of the field. + enum: + - date + - text + - number + contactdb_recipient_count: + type: object + properties: + recipient_count: + type: number + description: The count of recipients. + required: + - recipient_count + user_scheduled_send_status: + allOf: + - $ref: '#/definitions/mail_batch_id' + - type: object + description: The status of the scheduled send. + properties: + status: + type: string + description: The status of the scheduled send. + enum: + - cancel + - pause + required: + - status contactdb_list: title: ContactDB lists type: object @@ -12507,47 +11766,15 @@ definitions: first_name: type: string last_name: - type: string - phone: - type: string - state: - type: string - website: - type: string - zip: - type: string - monitor: - title: Create monitor settings request - type: object - properties: - email: - type: string - description: The email address to send emails at the frequency specified for monitoring. - format: email - frequency: - type: number - description: 'The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. ' - required: - - email - - frequency - api_key_name_id: - type: object - properties: - api_key_id: - type: string - description: 'The ID of your API Key. ' - name: - type: string - description: The name of your API Key. - mail_settings_forward_bounce: - type: object - properties: - email: - type: - - string - - 'null' - enabled: - type: boolean + type: string + phone: + type: string + state: + type: string + website: + type: string + zip: + type: string 'global:ErrorResponse': type: object properties: @@ -12762,150 +11989,822 @@ definitions: properties: id: type: integer - description: The ID of the domain whitelabel. + description: The ID of the domain whitelabel. + domain: + type: string + description: The domain that this whitelabel was created for. + subdomain: + type: string + description: The subdomain that was used to create this whitelabel. + username: + type: string + description: The username of the account that this whitelabel is associated with. + user_id: + type: integer + description: The user_id of the account that this whitelabel is associated with. + ips: + type: array + description: The IP addresses that are included in the SPF record for this whitelabel. + items: {} + custom_spf: + type: boolean + description: Indicates if this whitelabel uses custom SPF. + default: + type: boolean + description: Indicates if this is the default whitelabel. + legacy: + type: boolean + description: Indicates if this whitelabel was created using the legacy whitelabel tool. + automatic_security: + type: boolean + description: Indicates if this whitelabel uses automated security. + valid: + type: boolean + description: Indicates if this is a valid whitelabel. + dns: + type: object + description: The DNS records for this whitelabel. + required: + - mail_server + - subdomain_spf + - domain_spf + - dkim + properties: + mail_server: + type: object + description: Designates which mail server is responsible for accepting messages from a domain. + required: + - host + - type + - data + - valid + properties: + host: + type: string + description: The domain sending the messages. + type: + type: string + description: They type of DNS record. + data: + type: string + description: The mail server responsible for accepting messages from the sending domain. + valid: + type: boolean + description: Indicates if this is a valid DNS record. + subdomain_spf: + type: object + description: The SPF record for the subdomain used to create this whitelabel. + required: + - host + - type + - data + - valid + properties: + host: + type: string + description: The domain that this SPF record will be used to authenticate. + type: + type: string + description: The type of data in the SPF record. + data: + type: string + description: The SPF record. + valid: + type: boolean + description: Indicates if this is a valid SPF record. + domain_spf: + type: object + description: The SPF record for the root domain. + required: + - host + - type + - data + - valid + properties: + host: + type: string + description: The root domain that this SPF record will be used to authenticate. + type: + type: string + description: The type of data in the SPF record. + data: + type: string + description: The SPF record. + valid: + type: boolean + description: Indicates if the SPF record is valid. + dkim: + type: object + description: The DKIM record for messages sent using this whitelabel. + required: + - host + - type + - data + - valid + properties: + host: + type: string + description: The DNS labels for the DKIM signature. + type: + type: string + description: The type of data in the DKIM record. + data: + type: string + description: The DKIM record. + valid: + type: boolean + description: Indicates if the DKIM record is valid. + required: + - id + - domain + - subdomain + - username + - user_id + - ips + - custom_spf + - default + - legacy + - automatic_security + - valid + - dns + transactional_template: + type: object + properties: + id: + type: string + description: The ID of the transactional template. + name: + type: string + description: The name for the transactional template. + maxLength: 100 + versions: + type: array + description: The different versions of this transactional template. + items: + $ref: '#/definitions/transactional_template_version' + required: + - id + - name + suppression_group: + type: object + properties: + id: + type: number + description: The id of the suppression group. + name: + type: string + description: The name of the suppression group. Each group created by a user must have a unique name. + maxLength: 30 + description: + type: string + description: A description of the suppression group. + maxLength: 100 + last_email_sent_at: + type: 'null' + is_default: + type: boolean + default: 'false' + description: Indicates if this is the default suppression group. + required: + - id + - name + - description + advanced_stats_country: + type: object + properties: + date: + type: string + description: The date that the events occurred. + stats: + type: array + description: The statistics of the email events. + items: + type: object + properties: + type: + type: string + description: The type of segmentation. + name: + type: string + description: The name of the specific segmentation. + metrics: + type: object + description: The individual events and their stats. + required: + - clicks + - opens + - unique_clicks + - unique_opens + properties: + clicks: + type: integer + description: The number of links that were clicked in your emails. + opens: + type: integer + description: The total number of times your emails were opened by recipients. + unique_clicks: + type: integer + description: The number of unique recipients who clicked links in your emails. + unique_opens: + type: integer + description: The number of unique recipients who opened your emails. + required: + - type + - name + - metrics + required: + - date + - stats + advanced_stats_opens: + type: object + properties: + date: + type: string + description: The date that the events occurred. + stats: + type: array + description: The statistics of the email events. + items: + type: object + properties: + type: + type: string + description: The type of segmentation. + name: + type: string + description: The name of the specific segmentation. + metrics: + type: object + description: The individual events and their stats. + required: + - opens + - unique_opens + properties: + opens: + type: integer + description: The total number of times your emails were opened by recipients. + unique_opens: + type: integer + description: The number of unique recipients who opened your emails. + required: + - type + - name + - metrics + required: + - date + - stats + advanced_stats_clicks: + type: object + properties: + date: + type: string + description: The date that the events occurred. + stats: + type: array + description: The statistics of the email events. + items: + type: object + properties: + type: + type: string + description: The type of segmentation. + name: + type: string + description: The name of the specific segmentation. + metrics: + type: object + description: The individual events and their stats. + required: + - clicks + - unique_clicks + properties: + clicks: + type: integer + description: The number of links that were clicked in your emails. + unique_clicks: + type: integer + description: The number of unique recipients who clicked links in your emails. + required: + - type + - name + - metrics + required: + - date + - stats + advanced_stats_mailbox_provider: + type: object + properties: + date: + type: string + description: The date that the events occurred. + stats: + type: array + description: The statistics of the email events. + items: + type: object + properties: + type: + type: string + description: The type of segmentation. + name: + type: string + description: The name of the specific segmentation. + metrics: + type: object + description: The individual events and their stats. + required: + - clicks + - opens + - unique_clicks + - unique_opens + - blocks + - bounces + - deferred + - delivered + - drops + - spam_reports + properties: + clicks: + type: integer + description: The number of links that were clicked in your emails. + opens: + type: integer + description: The total number of times your emails were opened by recipients. + unique_clicks: + type: integer + description: The number of unique recipients who clicked links in your emails. + unique_opens: + type: integer + description: The number of unique recipients who opened your emails. + blocks: + type: integer + description: The number of emails that were not allowed to be delivered by ISPs. + bounces: + type: integer + description: The number of emails that bounced instead of being delivered. + deferred: + type: integer + description: The number of emails that temporarily could not be delivered. + delivered: + type: integer + description: The number of emails SendGrid was able to confirm were actually delivered to a recipient. + drops: + type: integer + description: The number of emails that were not delivered due to the recipient email address being on a suppression list. + spam_reports: + type: integer + description: The number of recipients who marked your email as spam. + required: + - type + - name + - metrics + required: + - date + - stats + stats: + type: array + items: + type: object + properties: + date: + type: string + description: The date that the statistics were gathered. + stats: + type: array + description: The list of statistics. + items: + type: object + properties: + type: + type: string + description: The type of segmentation. + name: + type: string + description: The name of the specific segmentation. + metrics: + type: object + description: The individual events and their statistics. + properties: + blocks: + type: integer + description: The number of emails that were not allowed to be delivered by ISPs. + bounce_drops: + type: integer + description: The number of emails that were dropped because of a bounce. + bounces: + type: integer + description: The number of emails that bounced instead of being delivered. + clicks: + type: integer + description: The number of links that were clicked in your emails. + deferred: + type: integer + description: 'The number of emails that temporarily could not be delivered. ' + delivered: + type: integer + description: The number of emails SendGrid was able to confirm were actually delivered to a recipient. + invalid_emails: + type: integer + description: The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid. + opens: + type: integer + description: The total number of times your emails were opened by recipients. + processed: + type: integer + description: 'Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed.' + requests: + type: integer + description: The number of emails that were requested to be delivered. + spam_report_drops: + type: integer + description: The number of emails that were dropped due to a recipient previously marking your emails as spam. + spam_reports: + type: integer + description: The number of recipients who marked your email as spam. + unique_clicks: + type: integer + description: The number of unique recipients who clicked links in your emails. + unique_opens: + type: integer + description: The number of unique recipients who opened your emails. + unsubscribe_drops: + type: integer + description: The number of emails dropped due to a recipient unsubscribing from your emails. + unsubscribes: + type: integer + description: The number of recipients who unsubscribed from your emails. + link_whitelabel: + type: object + properties: + id: + type: integer + description: The id of the link whitelabel. domain: type: string - description: The domain that this whitelabel was created for. + description: The root domain for this link whitelabel. subdomain: type: string - description: The subdomain that was used to create this whitelabel. + description: The subdomain used to generate the DNS records for this link whitelabel. This subdomain must be different from the subdomain used for your domain whitelabel. username: type: string - description: The username of the account that this whitelabel is associated with. + description: The username of the account that this link whitelabel is associated with. user_id: type: integer - description: The user_id of the account that this whitelabel is associated with. - ips: - type: array - description: The IP addresses that are included in the SPF record for this whitelabel. - items: {} - custom_spf: - type: boolean - description: Indicates if this whitelabel uses custom SPF. + description: The id of the user that this whitelabel is associated with. default: type: boolean - description: Indicates if this is the default whitelabel. - legacy: - type: boolean - description: Indicates if this whitelabel was created using the legacy whitelabel tool. - automatic_security: - type: boolean - description: Indicates if this whitelabel uses automated security. + description: Indicates if this is the default link whitelabel. + enum: + - true + - false valid: type: boolean - description: Indicates if this is a valid whitelabel. + description: Indicates if this link whitelabel is valid. + enum: + - true + - false + legacy: + type: boolean + description: Indicates if this link whitelabel was created using the legacy whitelabel tool. + enum: + - true + - false dns: type: object - description: The DNS records for this whitelabel. + description: The DNS records generated for this link whitelabel. required: - - mail_server - - subdomain_spf - - domain_spf - - dkim + - domain_cname properties: - mail_server: + domain_cname: type: object - description: Designates which mail server is responsible for accepting messages from a domain. + description: The DNS record generated to point to your link whitelabel subdomain. required: - - host + - valid - type + - host - data - - valid properties: - host: - type: string - description: The domain sending the messages. - type: - type: string - description: They type of DNS record. - data: - type: string - description: The mail server responsible for accepting messages from the sending domain. valid: type: boolean - description: Indicates if this is a valid DNS record. - subdomain_spf: - type: object - description: The SPF record for the subdomain used to create this whitelabel. - required: - - host - - type - - data - - valid - properties: - host: - type: string - description: The domain that this SPF record will be used to authenticate. + description: Indicates if the DNS record is valid. + enum: + - true + - false type: type: string - description: The type of data in the SPF record. + description: The type of DNS record that was generate. + enum: + - cname + - txt + - mx + host: + type: string + description: The domain that this whitelabel will use when whitelabeling the links in your email. + format: hostname data: type: string - description: The SPF record. - valid: - type: boolean - description: Indicates if this is a valid SPF record. - domain_spf: + description: The domain that the DNS record points to. + format: hostname + owner_cname: type: object - description: The SPF record for the root domain. - required: - - host - - type - - data - - valid + description: The DNS record generated to verify who created the link whitelabel. properties: - host: - type: string - description: The root domain that this SPF record will be used to authenticate. + valid: + type: boolean + description: Indicates if the DNS record is valid. + enum: + - true + - false type: type: string - description: The type of data in the SPF record. + description: The type of DNS record generated. + enum: + - cname + - txt + - mx + host: + type: string + description: Used to verify the link whitelabel. The subdomain of this domain is the user id of the user who created the link whitelabel. + format: hostname data: type: string - description: The SPF record. - valid: - type: boolean - description: Indicates if the SPF record is valid. - dkim: - type: object - description: The DKIM record for messages sent using this whitelabel. + description: The domain that the DNS record points to. + format: hostname required: + - valid - host - - type - data - - valid - properties: - host: - type: string - description: The DNS labels for the DKIM signature. - type: - type: string - description: The type of data in the DKIM record. - data: - type: string - description: The DKIM record. - valid: - type: boolean - description: Indicates if the DKIM record is valid. required: - id - domain - subdomain - username - user_id - - ips - - custom_spf - default - - legacy - - automatic_security - valid + - legacy - dns -basePath: /v3 -host: 'https://api.sendgrid.com' -schemes: - - http - - https -produces: - - application/json -consumes: - - application/json + ip_warmup_response: + type: array + items: + type: object + properties: + ip: + type: string + start_date: + type: integer + ip_pool: + type: object + properties: + name: + type: string + category_stats: + type: object + properties: + date: + type: string + description: The date the statistics were gathered. + stats: + type: array + items: + type: object + properties: + metrics: + type: object + properties: + blocks: + type: integer + description: The number of emails that were not allowed to be delivered by ISPs. + bounce_drops: + type: integer + description: The number of emails that were dropped because of a bounce. + bounces: + type: integer + description: The number of emails that bounced instead of being delivered. + clicks: + type: integer + description: The number of links that were clicked. + deferred: + type: integer + description: The number of emails that temporarily could not be delivered. + delivered: + type: integer + description: The number of emails SendGrid was able to confirm were actually delivered to a recipient. + invalid_emails: + type: integer + description: The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid. + opens: + type: integer + description: The total number of times your emails were opened by recipients. + processed: + type: integer + description: 'Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed.' + requests: + type: integer + description: The number of emails that were requested to be delivered. + spam_report_drops: + type: integer + description: The number of emails that were dropped due to a recipient previously marking your emails as spam. + spam_reports: + type: integer + description: The number of recipients who marked your email as spam. + unique_clicks: + type: integer + description: The number of unique recipients who clicked links in your emails. + unique_opens: + type: integer + description: The number of unique recipients who opened your emails. + unsubscribe_drops: + type: integer + description: The number of emails dropped due to a recipient unsubscribing from your emails. + unsubscribes: + type: integer + description: The number of recipients who unsubscribed from your emails. + required: + - blocks + - bounce_drops + - bounces + - clicks + - deferred + - delivered + - invalid_emails + - opens + - processed + - requests + - spam_report_drops + - spam_reports + - unique_clicks + - unique_opens + - unsubscribe_drops + - unsubscribes + name: + type: string + description: The name of the category. + type: + type: string + description: How you are segmenting your statistics. + required: + - type + required: + - date + ip_whitelabel: + type: object + properties: + id: + type: integer + description: The id of the IP whitelabel. + ip: + type: string + description: The IP address that this whitelabel was created for. + rdns: + type: string + description: The reverse DNS record for the IP address. This points to the IP whitelabel subdomain. + users: + type: array + description: The users who are able to send mail from the IP. + items: + type: object + properties: + username: + type: string + description: The username of the user who can send mail from this IP. + user_id: + type: integer + description: The ID of the user who can send mail from this IP. + required: + - username + - user_id + subdomain: + type: string + description: The subdomain created for this IP whitelabel. This is where the rDNS record points. + domain: + type: string + description: 'The root, or sending, domain.' + valid: + type: boolean + description: Indicates if this is a valid whitelabel. + legacy: + type: boolean + description: Indicates if this whitelabel was created using the legacy whitelabel tool. + a_record: + type: object + required: + - valid + - type + - host + - data + properties: + valid: + type: boolean + description: Indicates if the a_record is valid. + type: + type: string + description: The type of DNS record. + host: + type: string + description: This is the web address that will be mapped to the IP address. + data: + type: string + description: The IP address being whitelabeled. + required: + - id + - ip + - rdns + - users + - subdomain + - domain + - valid + - legacy + - a_record + google_analytics_settings: + type: object + properties: + enabled: + type: boolean + description: Indicates if Google Analytics is enabled. + utm_campaign: + type: string + description: The name of the campaign. + utm_content: + type: string + description: Used to differentiate ads + utm_medium: + type: string + description: 'Name of the marketing medium (e.g. "Email").' + utm_source: + type: string + description: 'Name of the referrer source. ' + utm_term: + type: string + description: Any paid keywords. + subscription_tracking_settings: + type: object + properties: + enabled: + type: boolean + description: Indicates if subscription tracking is enabled. + html_content: + type: string + description: 'The information and HTML for your unsubscribe link. ' + landing: + type: string + description: 'The HTML that will be displayed on the page that your customers will see after clicking unsubscribe, hosted on SendGrid’s server.' + plain_content: + type: string + description: 'The information in plain text for your unsubscribe link. You should have the “<% %>” tag in your content, otherwise the user will have no URL for unsubscribing.' + replace: + type: string + description: Your custom defined replacement tag for your templates. Use this tag to place your unsubscribe content anywhere in your emailtemplate. + url: + type: string + description: The URL where you would like your users sent to unsubscribe. + mail_settings_footer: + type: object + properties: + enabled: + type: boolean + description: Indicates if the Footer mail setting is currently enabled. + html_content: + type: string + description: The custom HTML content of your email footer. + plain_content: + type: string + description: The plain text content of your email footer. + mail_settings_spam_check: + type: object + properties: + enabled: + type: boolean + description: Indicates if your Spam Checker mail setting is enabled. + max_score: + type: integer + default: 5 + description: 'The spam threshold. Can range from 1 to 10. The lower the number, the more strict the filtering.' + minimum: 1 + maximum: 10 + url: + type: string + description: The inbound parse URL where you would like the spam messages to be sent to. + required: + - enabled + mail_settings_bounce_purge: + type: object + properties: + enabled: + type: boolean + description: Indicates if the bounce purge mail setting is enabled. + soft_bounces: + type: + - integer + - 'null' + description: 'The number of days, after which SendGrid will purge all contacts from your soft bounces suppression lists.' + hard_bounces: + type: + - integer + - 'null' + description: 'The number of days, after which SendGrid will purge all contacts from your hard bounces suppression lists.' +securityDefinitions: + Authorization: + name: Authorization + type: apiKey + in: header diff --git a/temp.json b/temp.json deleted file mode 100644 index 2850ce3..0000000 --- a/temp.json +++ /dev/null @@ -1,18278 +0,0 @@ -{ - "swagger": "2.0", - "schemes": [ - "http", - "https" - ], - "basePath": "/v3", - "host": "api.sendgrid.com", - "info": { - "version": "3.0", - "title": "DX - v3 - Officially Documented Only - DO NOT EDIT", - "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\n\n" - }, - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/partner_settings/sendwithus": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update SendWithUs Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "properties": { - "body": { - "description": "", - "schema": { - "type": "object" - } - } - }, - "required": [ - "body" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object" - } - } - }, - "summary": "" - }, - "get": { - "description": "", - "operationId": "Get SendWithUs Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object" - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/groups/{group_id}": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The id of the suppression group you want to delete.", - "required": true, - "type": "integer" - } - ], - "delete": { - "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 a suppression group.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "A single suppression group object with all its details", - "security": [ - { - "Authorization": [] - } - ] - }, - "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 information on a single suppression group.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "allOf": [ - { - "$ref": "#/definitions/suppression_group" - }, - { - "type": "object", - "properties": { - "unsubscribes": { - "type": "integer", - "description": "The unsubscribes associated with this group." - } - } - } - ] - }, - "examples": { - "application/json": { - "id": 100, - "name": "Newsletters", - "description": "Our monthly newsletter.", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 400 - } - } - } - }, - "summary": "You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the “one-cl", - "security": [ - { - "Authorization": [] - } - ] - }, - "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": "Update a suppression group.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The id of the suppression group." - }, - "name": { - "type": "string", - "description": "The name of the suppression group. Each group created by a user must have a unique name.", - "maxLength": 30 - }, - "description": { - "type": "string", - "description": "The description of the suppression group.", - "maxLength": 100 - }, - "is_default": { - "type": "boolean", - "description": "Indicates if the suppression group is set as the default group." - } - }, - "required": [ - "name" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/suppression_group" - }, - "examples": { - "application/json": { - "id": 103, - "name": "Item Suggestions", - "description": "Suggestions for items our users might like." - } - } - } - }, - "summary": "" - } - }, - "/tracking_settings/open": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get Open Tracking Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enabled": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update Open Tracking Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enabled": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mailbox_providers/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", - "operationId": "Retrieve email statistics by mailbox provider.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of results to include on each page.", - "required": false, - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The number of results to exclude.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the stats. Must be either \"day\", \"wee\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "mailbox_providers", - "in": "query", - "description": "The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times.", - "required": false, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_mailbox_provider" - } - }, - "examples": { - "application/json": [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 1, - "drops": 0, - "opens": 1, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 2, - "drops": 0, - "opens": 2, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 2 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "mailbox_provider", - "name": "Gmail", - "metrics": { - "blocks": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "drops": 0, - "opens": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/lists/{list_id}/recipients": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "List all the recipients currently on a specific list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List Recipients on a List", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "page", - "in": "query", - "description": "Page index of first recipient to return (must be a positive integer)", - "required": false, - "type": "integer" - }, - { - "name": "page_size", - "in": "query", - "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", - "required": false, - "type": "integer" - }, - { - "name": "list_id", - "in": "query", - "description": "The ID of the list whose recipients you are requesting.", - "required": true, - "type": "number" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_recipient" - } - } - } - }, - "examples": { - "application/json": { - "recipients": [ - { - "created_at": 1433348344, - "custom_fields": [ - { - "id": 6234, - "name": "age", - "type": "number", - "value": null - }, - { - "id": 6233, - "name": "country", - "type": "text", - "value": null - }, - { - "id": 6235, - "name": "fname", - "type": "text", - "value": "Example" - }, - { - "id": 6239, - "name": "lname", - "type": "text", - "value": "User" - }, - { - "id": 6240, - "name": "lname", - "type": "text", - "value": null - } - ], - "email": "example@example.com", - "first_name": "Example", - "id": "ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv==", - "last_clicked": 1438616117, - "last_emailed": 1438613272, - "last_name": "User", - "last_opened": 1438616109, - "updated_at": 1438616119 - } - ] - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is not a valid integer" - }, - { - "field": "page", - "message": "Returned if page is not a valid integer" - }, - { - "field": "page", - "message": "Returned if page is less than 1" - }, - { - "field": "page_size", - "message": "Returned if page_size is not a valid integer" - }, - { - "field": "page_size", - "message": "Returned if page_size is less than 1 or greater than 1000" - } - ] - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Add Multiple Recipients to a List", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The list to add your recipients to. ", - "required": true, - "type": "number" - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not a valid integer\"\n\"\" : \"Returned if no valid recipient ids were passed\"\n\"\" : \"Returned if no recipients were added\"\n\"\" : \"Returned if request body is invalid JSON\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "list_id is invalid" - }, - { - "field": "recipient_id", - "message": "no valid recipients were provided" - }, - { - "field": null, - "message": "no recipients were added" - }, - { - "field": null, - "message": "request body is invalid JSON" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"list_id\": \"Returned if list_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "list_id does not exist" - }, - { - "field": "recipient_id", - "message": "recipient_id does not exist" - } - ] - } - } - } - }, - "summary": "Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they ", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/templates/{template_id}/versions": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "**This endpoint allows you to create a new version of a template.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", - "operationId": "Create a new transactional template version.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/transactional_template_version" - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The id of the new transactional template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that this transactional template version was updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_template_version" - } - }, - "required": [ - "id", - "updated_at" - ] - }, - "examples": { - "application/json": { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-03-19 18:56:33" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/default": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve the default whitelabel for a domain.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| domain | string |The domain to find a default domain whitelabel for. |", - "operationId": "Get the default domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/{id}/ips/{ip}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "ip", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "**This endpoint allows you to remove a domain's IP address from that domain's whitelabel.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain whitelabel to delete the IP from. |\n| ip | string | IP to remove from the domain whitelabel. |", - "operationId": "Remove an IP from a domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/templates/{template_id}/versions/{version_id}": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "version_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "**This endpoint allows you to retrieve a specific version of a template.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", - "operationId": "Retrieve a specific transactional template version.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that the template version was last updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_template_version" - } - }, - "required": [ - "id", - "updated_at" - ] - }, - "examples": { - "application/json": { - "id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f", - "template_id": "d51480ca-ca3f-465c-bc3e-ceb71d73c38d", - "active": 1, - "name": "version 1 name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-03-19 18:56:33" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "**This endpoint allows you to delete one of your transactional template versions.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", - "operationId": "Delete a transactional template version.", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "**This endpoint allows you to edit a version of one of your transactional templates.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", - "operationId": "Edit a transactional template version.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "active": { - "type": "integer", - "description": "Indicates if the template version is active." - }, - "name": { - "type": "string", - "description": "The name of the template version." - }, - "html_content": { - "type": "string", - "description": "The HTML content of the template version." - }, - "plain_content": { - "type": "string", - "description": "The text/plain content of the template version." - }, - "subject": { - "type": "string", - "description": "The subject of the template version." - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that the template version was last updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_template_version" - } - }, - "required": [ - "id", - "updated_at" - ] - }, - "examples": { - "application/json": { - "id": "5997fcf6-2b9f-484d-acd5-7e9a99f0dc1f", - "template_id": "d51480ca-ca3f-465c-bc3e-ceb71d73c38d", - "active": 1, - "name": "version 1 name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-03-19 18:56:33" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/templates/{template_id}/versions/{version_id}/activate": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "version_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "**This endpoint allows you to activate a version of one of your templates.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", - "operationId": "Activate a transactional template version.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." - }, - "updated_at": { - "type": "string", - "description": "The date and time that the version was last updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_template_version" - } - }, - "required": [ - "id", - "updated_at" - ] - }, - "examples": { - "application/json": { - "id": "8aefe0ee-f12b-4575-b5b7-c97e21cb36f3", - "template_id": "e3a61852-1acb-4b32-a1bc-b44b3814ab78", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "updated_at": "2014-06-12 11:33:00" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/pools/{pool_name}": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "", - "operationId": "List the IPs in a specified pool.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "pool_name": { - "type": "string" - }, - "ips": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "", - "operationId": "Delete an IP pool.", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "put": { - "description": "", - "operationId": "Update an IP pool’s name.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/ip_pool" - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_pool" - }, - "examples": { - "application/json": { - "name": "new_pool_name" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/{domain_id}/subuser": { - "parameters": [ - { - "name": "domain_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "**This endpoint allows you to associate a specific domain whitelabel with a subuser.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| domain_id | integer | ID of the domain whitelabel to associate with the subuser. |", - "operationId": "Associate a domain whitelabel with a given user.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Username to associate with the domain whitelabel." - } - }, - "required": [ - "username" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/subuser": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| username | string | Username of the subuser to find associated whitelabels for. |", - "operationId": "List the domain whitelabel associated with the given user.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "mail@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "**This endpoint allows you to disassociate a specific whitelabel from a subuser.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n| username | string | required | Username for the subuser to find associated whitelabels for. |", - "operationId": "Disassociate a domain whitelabel from a given user.", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "" - } - }, - "summary": "Domain Whitelabels can be associated with subusers via parent accounts. This functionality allows\nsubusers to send mail", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/{id}/ips": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "**This endpoint allows you to add an IP address to a domain whitelabel.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain to which you are adding an IP |", - "operationId": "Add an IP to a domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." - } - }, - "required": [ - "ip" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "ips": [], - "custom_spf": true, - "default": false, - "legacy": false, - "automatic_security": false, - "valid": false, - "dns": { - "mail_server": { - "host": "mail.example.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false - }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false - }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/links/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The id of the link whitelabel you want to retrieve.", - "required": true, - "type": "integer" - } - ], - "get": { - "description": "**This endpoint allows you to retrieve a specific link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Retrieve a Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/link_whitelabel" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "**This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Update a Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "default": { - "type": "boolean", - "description": "Indicates if the link whitelabel is set as the default, or fallback, whitelabel.", - "enum": [ - true, - false - ] - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/link_whitelabel" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": true, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "**This endpoint allows you to delete a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Delete a Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "" - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/{domain_id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The id of the domain whitelabel.", - "required": true, - "type": "number" - } - ], - "patch": { - "description": "**This endpoint allows you to update the settings for a domain whitelabel.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", - "operationId": "Update a domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "default": { - "type": "boolean", - "default": "false", - "description": "Indicates whether this domain whitelabel should be considered the default." - }, - "custom_spf": { - "type": "boolean", - "default": "false", - "description": "Indicates whether to generate a custom SPF record for manual security." - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "title": "Update a Domain response", - "type": "object", - "properties": { - "default false": { - "description": "Inidcates whether this domain whitelabel should be considered the default. Defaults to false.", - "type": "boolean" - }, - "custom_spf false": { - "description": "Indicates whether to generate a custom SPF record for manual security. Defaults to false.", - "type": "boolean" - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "**This endpoint allows you to retrieve a specific domain whitelabel.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n", - "operationId": "Retrieve a domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel::domain" - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "**This endpoint allows you to delete a domain whitelabel.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", - "operationId": "Delete a domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "" - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/lists": { - "parameters": [], - "delete": { - "description": "Delete multiple lists.\n\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Delete Multiple lists", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"id\" : \"Returned if all list ids are not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "list id was invalid" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Create a list for your recipients.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Create a List", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "title": "Create a List request", - "type": "object", - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_list" - }, - "examples": { - "application/json": { - "id": 1, - "name": "your list name", - "recipient_count": 0 - } - } - }, - "400": { - "description": "\"name\" : \"Returned if list name is a duplicate of an existing list or segment\"\n\"name\" : \"Returned if list name is not a string\"\n\"\" : \"Returned if request body is invalid JSON\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "Returned if request body is invalid JSON" - }, - { - "field": "name", - "message": "Returned if list name is not a string" - }, - { - "field": "name", - "message": "Returned if list name is a duplicate of an existing list or segment" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Returns an empty list if you GET and no lists exist on your account.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List All Lists", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "List All Lists response", - "type": "object", - "properties": { - "lists": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_list" - } - } - }, - "required": [ - "lists" - ] - }, - "examples": { - "application/json": { - "lists": [ - { - "id": 1, - "name": "the jones", - "recipient_count": 1 - } - ] - } - } - } - }, - "summary": "Returns an empty list if you GET and no lists exist on your account.", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers/{subuser_name}/monitor": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "operationId": "Create monitor settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/monitor" - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/monitor" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "frequency": 50000 - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "User already has a monitor" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "operationId": "Delete monitor settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" - } - ] - } - } - } - }, - "summary": "" - }, - "put": { - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "operationId": "Update Monitor Settings for a subuser", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/monitor" - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/monitor" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "frequency": 500 - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "email", - "message": "Email is required" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "operationId": "Retrieve monitor settings for a subuser", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/monitor" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "frequency": 500 - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/links/{link_id}/subuser": { - "parameters": [ - { - "name": "link_id", - "in": "path", - "description": "The id of the link whitelabel you want to associate.", - "required": true, - "type": "integer" - } - ], - "post": { - "description": "**This endpoint allows you to associate a link whitelabel with a subuser account.**\n\nLink whitelables can be associated with subusers from the parent account. This functionality allows\nsubusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account\nmust first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Associate a Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the subuser account that you want to associate the link whitelabel with." - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/link_whitelabel" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/links/subuser": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve the associated link whitelabel for a subuser.**\n\nLink whitelables can be associated with subusers from the parent account. This functionality allows\nsubusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account\nmust first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Retrieve Associated Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of the subuser to retrieve associated link whitelabels for.", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/link_whitelabel" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "**This endpoint allows you to disassociate a link whitelabel from a subuser.**\n\nLink whitelables can be associated with subusers from the parent account. This functionality allows\nsubusers to send mail using their parent's linke whitelabels. To associate a link whitelabel, the parent account\nmust first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface.\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Disassociate a Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of the subuser account that you want to disassociate a link whitelabel from.", - "required": true, - "type": "string" - } - ], - "responses": { - "204": { - "description": "" - } - }, - "summary": "Link Whitelabels can be associated with subusers via parent accounts. This functionality allows\nsubusers to send mail o", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/segments": { - "parameters": [], - "get": { - "description": "Get all your segments.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List All Segments", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "List All Segments response", - "type": "object", - "properties": { - "segments": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_segments" - } - } - }, - "required": [ - "segments" - ] - }, - "examples": { - "application/json": { - "segments": [ - { - "id": 1234, - "name": "Age segments < 25", - "conditions": [ - { - "field": "age", - "value": "25", - "operator": "lt" - } - ], - "recipient_count": 8 - }, - { - "id": 2345, - "name": "email address - gmail", - "conditions": [ - { - "field": "email", - "value": "@gmail.com", - "operator": "contains" - } - ], - "recipient_count": 0 - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Create a segment. All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment.\n\nList Id:\n\n* Send this to segment from an existing list\n* Don't send this in order to segment from your entire contactdb.\n\nValid operators for create and update depend on the type of the field you are segmenting: \n\n* **Dates:** \"eq\", \"ne\", \"lt\" (before), \"gt\" (after) \n* **Text:** \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value) \n* **Numbers:** \"eq\", \"lt\", \"gt\" \n* **Email Clicks and Opens:** \"eq\" (opened), \"ne\" (not opened) \n\nSegment conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. \n\nSegments may contain multiple condtions, joined by an \"and\" or \"or\" in the \"and_or\" field. The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Create a Segment", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/contactdb_segments" - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_segments_with_id" - }, - "examples": { - "application/json": { - "id": 1, - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - }, - { - "field": "last_clicked", - "value": "01/02/2015", - "operator": "gt", - "and_or": "and" - }, - { - "field": "clicks.campaign_identifier", - "value": "513", - "operator": "eq", - "and_or": "or" - } - ], - "recipient_count": 0 - } - } - }, - "400": { - "description": "\"name\" : \"Returned if the name is not valid\"\n\"list_id\" : \"Returned if the list_id is not valid\"\n\"and_or\" : \"Returned if and_or and set value is not passed into the request body\"\n\"and_or\" : \"Returned if and_or is set on the only condition passed\"\n\"and_or\" : \"Returned if and_or is set on all conditions\"\n\"and_or\" : \"Returned if and_or is not set on more than one condition and less than all conditions\"\n\"operator\" : \"Returned if operator and set value is not passed into the request body\"\n\"value\" : \"Returned if value and set value is not passed into the request body\"\n\"field\" : \"Returned if field and set value is not passed into the request body\"\n\"\" : \"Returned if request body is not valid json\"\n\"\" : \"Returned if invalid value is passed into one of the request body parameters\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "request body is not valid json" - }, - { - "message": "invalid value is passed into one of the request body parameters" - }, - { - "field": "field", - "message": "field and set value is not passed into the request body" - }, - { - "field": "value", - "message": "value and set value is not passed into the request body" - }, - { - "field": "operator", - "message": "operator and set value is not passed into the request body" - }, - { - "field": "and_or", - "message": "and_or is not set on more than one condition and less than all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on the only condition passed" - }, - { - "field": "and_or", - "message": "and_or and set value is not passed into the request body" - }, - { - "field": "list_id", - "message": "the list_id is not valid" - }, - { - "field": "name", - "message": "the name is not valid" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/segments/{segment_id}": { - "parameters": [ - { - "name": "segment_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "Delete a segment from your contactdb. You also have the option to delete all the contacts from your contactdb who were in this segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Delete a Segment", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "delete_contacts", - "in": "query", - "description": "True to delete all contacts matching the segment in addition to deleting the segment", - "type": "boolean" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not a valid boolean\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "segment_id", - "message": "Returned if segment_id is not valid" - }, - { - "field": "delete_contacts", - "message": "Returned if delete_contacts is not a valid boolean" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "segment_id", - "message": "segment_id does not exist" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Get a single segment by ID.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Retrieve a Segment", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "segment_id", - "in": "query", - "description": "The ID of the segment you want to request.", - "required": true, - "type": "number" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_segments" - }, - "examples": { - "application/json": { - "id": 1, - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ], - "recipient_count": 1 - } - } - }, - "400": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "if segment_id is not valid" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "segment_id not found" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "Update a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Update a segment", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "segment_id", - "in": "query", - "description": "The ID of the segment you are updating.", - "type": "string" - }, - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "list_id": { - "type": "number", - "description": "The list ID you would like this segment to be built from." - }, - "conditions": { - "type": "array", - "description": "The conditions by which this segment should be created.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" - } - } - }, - "required": [ - "name" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_segments" - }, - "examples": { - "application/json": { - "id": 5, - "name": "The Millers", - "list_id": 5, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ], - "recipient_count": 1 - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "request body is not valid json" - }, - { - "message": "invalid value is passed into one of the request body parameters" - }, - { - "segment_id": "segment_id", - "message": "segment id is not valid" - }, - { - "field": "field", - "message": "field and set value is not passed into the request body" - }, - { - "field": "value", - "message": "value and set value is not passed into the request body" - }, - { - "field": "operator", - "message": "operator and set value is not passed into the request body" - }, - { - "field": "and_or", - "message": "and_or is not set on more than one condition and less than all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on all conditions" - }, - { - "field": "and_or", - "message": "and_or is set on the only condition passed" - }, - { - "field": "and_or", - "message": "and_or and set value is not passed into the request body" - }, - { - "field": "list_id", - "message": "the list_id is not valid" - }, - { - "field": "name", - "message": "the name is not valid" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/recipients/{recipient_id}/lists": { - "parameters": [ - { - "name": "recipient_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "Each recipient can be on many lists. This endpoint gives you the lists this recipient is associated to.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Get the Lists the Recipient Is On", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "recipient_id", - "in": "query", - "description": "The ID of the recipient you are requesting lists for.", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "lists": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_list" - } - } - } - }, - "examples": { - "application/json": { - "lists": [ - { - "id": 1234, - "name": "Example list", - "recipient_count": 42 - } - ] - } - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient ID is invalid" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for the recipient id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient id not found" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/recipients/{recipient_id}": { - "parameters": [ - { - "name": "recipient_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "Delete a single recipient from your contact database, by ID.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Delete a Recipient", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "recipient_id", - "in": "query", - "description": "The ID of the recipient to be deleted.", - "required": true, - "type": "string" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient not found" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "recipient_id is not valid" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Retrieve a single recipient by ID from your contact database.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Retrieve a single recipient", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "recipient_id", - "in": "query", - "description": "The ID of the created recipient.", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_recipient" - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"" - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"" - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/recipients/search": { - "parameters": [], - "get": { - "description": "Search the recipients in your contactdb.\n\nfield_name:\n\n* is a variable that is substituted for your actual custom field name from your recipient.\n* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)\n* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert\nyour epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to\nMon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through\nMon, 02 Feb 2015 23:59:59 GMT.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Get Recipients Matching Search Criteria", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "{field_name}", - "in": "query", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_recipient" - } - } - } - }, - "examples": { - "application/json": { - "recipients": [ - { - "created_at": 1422313607, - "email": "jones@example.com", - "first_name": null, - "id": "YUBh", - "last_clicked": null, - "last_emailed": null, - "last_name": "Jones", - "last_opened": null, - "updated_at": 1422313790, - "custom_fields": [ - { - "id": 23, - "name": "pet", - "value": "Fluffy", - "type": "text" - } - ] - } - ] - } - } - }, - "400": { - "description": "\"\" : \"Returned if no search params are specified\"\n\"field\" : \"Returned if the provided field is invalid or does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "The following parameters are not custom fields or reserved fields: [{field_name}]" - }, - { - "message": "No search params are specified" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "{% info %}\n\"field_name\"* is a variable that is substituted for your actual custom field name from your recipient.\nText f", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/recipients": { - "parameters": [], - "delete": { - "description": "Deletes one or more recipients. The body is a list of recipient ids to delete.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Delete Recipient", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "" - }, - "400": { - "description": "\"\" : \"Returned if no recipients are deleted\"\n\"\" : \"Returned if all of the provided recipient ids are invalid\"\n\"\" : \"Returned if request body is not valid json\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "No recipient ids provided" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "Deletes one or more recipients. The body is a list of recipient ids to delete.", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "Updates one or more recipients. The body is an array of recipient objects.\n\nIt is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Update Recipient", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_recipient_response" - } - }, - "400": { - "description": "\"\" : \"Returned if request body is not valid json\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "Updates one or more recipients. The body is a list of recipient objects.", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\nthe list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List Recipients [waiting on Bryan Adamson's response]", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "page", - "in": "query", - "description": "Page index of first recipients to return (must be a positive integer)", - "type": "integer" - }, - { - "name": "page_size", - "in": "query", - "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "title": "List Recipients response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object" - } - } - }, - "required": [ - "recipients" - ] - } - }, - "400": { - "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"\n\"page_size\" : \"Returned if page_size is less than 1 or greater than 1000\"" - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "{% info %}\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\n", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Add a recipient to your contactdb. It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Add recipients", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_recipient_response" - }, - "examples": { - "application/json": { - "error_count": 1, - "error_indices": [ - 2 - ], - "new_count": 2, - "persisted_recipients": [ - "YUBh", - "bWlsbGVyQG1pbGxlci50ZXN0" - ], - "updated_count": 0, - "errors": [ - { - "message": "Invalid email.", - "error_indices": [ - 2 - ] - } - ] - } - } - }, - "400": { - "description": "\"\" : \"Returned if request body is not valid json\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "Request body is not valid json" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/lists/{list_id}/recipients/{recipient_id}": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "recipient_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "Delete a single recipient from a list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Delete a Single Recipient from a Single List", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list you are taking this recipient away from.", - "required": true, - "type": "number" - }, - { - "name": "recipient_id", - "in": "query", - "description": "The ID of the recipient to take off the list.", - "required": true, - "type": "number" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "no valid recipients were provided" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id does not exist" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id does not exist" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Add a recipient to a list.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Add a Single Recipient to a List", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list to add the recipient to.", - "type": "number" - }, - { - "name": "recipient_id", - "in": "query", - "description": "The recipient you are adding to the list indicated.", - "type": "string" - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is invalid\"\n\"recipient_id\" : \"Returned if recipient_id is invalid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id is invalid" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id does not exist" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id does not exist" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/lists/{list_id}": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "Delete a list by ID.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Delete a List", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "delete_contacts", - "in": "query", - "description": "Adds the ability to delete all contacts on the list in addition to deleting the list.", - "type": "boolean", - "enum": [ - true, - false - ] - } - ], - "responses": { - "202": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "delete_contacts", - "message": "delete_contacts not a bool" - }, - { - "field": "list_id", - "message": "Returned if list_id is not valid" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "List not found: 5" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "Update the name of a list.\n\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Update a List", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list you are updating.", - "required": true, - "type": "number" - }, - { - "name": "body", - "in": "body", - "schema": { - "title": "Update a List request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name for your list. " - } - }, - "required": [ - "name" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "400": { - "description": "\"name\" : \"Returned if list name is a duplicate of existing list or segment\"\n\"name\" : \"Returned if list name is invalid or not provided\"\n\"list_id\" : \"Returned if list_id is not valid\"\n\"\" : \"Returned if request body is invalid JSON\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid id" - } - ] - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "List ID does not exist" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Get a single list. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Get a single list.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list to retrieve.", - "type": "number" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_list" - }, - "examples": { - "application/json": { - "id": 1, - "name": "listname", - "recipient_count": 0 - } - } - }, - "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid id" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "List ID does not exist" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/custom_fields": { - "parameters": [], - "get": { - "description": "Get all custom fields. \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List All Custom Fields", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "List All Custom Fields response", - "type": "object", - "properties": { - "custom_fields": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id" - } - } - }, - "required": [ - "custom_fields" - ] - }, - "examples": { - "application/json": { - "lists": [ - { - "id": 1, - "name": "the jones", - "recipient_count": 1 - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Create a custom field.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Create a Custom Field", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "name": { - "type": "string" - }, - "type": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "id": 1, - "name": "pet", - "type": "text" - } - } - }, - "400": { - "description": "\"\" : \"Returned if request body is invalid JSON\"\n\"type\" : \"Returned if custom field type is invalid or not provided\"\n\"name\" : \"Returned if custom field name is not provided\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "Returned if request body is invalid JSON" - }, - { - "field": "type", - "message": "Returned if custom field type is invalid or not provided" - }, - { - "field": "name", - "message": "Returned if custom field name is not provided" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/custom_fields/{custom_field_id}": { - "parameters": [ - { - "name": "custom_field_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "Delete a custom field by ID.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Delete a Custom Field", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "202": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "message": "Custom Field delete is processing." - } - } - }, - "400": { - "description": "\"id\" : \"Returned if custom_field_id is not valid\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Custom field in use by one or more segment conditions" - }, - { - "message": "Custom field ID does not exist" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Custom field ID does not exist" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Get a custom field by ID.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Get a Custom Field", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "custom_field_id", - "in": "query", - "description": "The ID of the custom field you would like to retrieve", - "required": true, - "type": "number" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_custom_field_with_id" - }, - "examples": { - "application/json": { - "id": 1, - "name": "pet", - "type": "text" - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid id" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Custom field ID does not exist" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/api_keys/{api_key_id}": { - "parameters": [ - { - "name": "api_key_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "patch": { - "description": "**Update the name of an existing API Key**\n\nA JSON request body with a \"name\" property is required.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are updating.|", - "operationId": "Update API keys", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name of the API Key." - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/api_key_name_id" - }, - "examples": { - "application/json": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope" - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "**Update the name of an existing API Key**\n\nA JSON request body with a \"name\" property is required.\n\nThe API Keys featur", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Retrieve a single api key.\nIf the API Key ID does not exist an HTTP 404 will be returned.\n\n## URI Parameters\n\n| Param | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key for which you are requesting information.|", - "operationId": "Get an existing API Key", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name you will use to describe this API Key." - }, - "scopes": { - "type": "array", - "description": "The individual permissions that you are giving to this API Key.", - "items": { - "type": "string" - } - } - }, - "required": [ - "name" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "items": { - "$ref": "#/definitions/api_key_name_id_scopes" - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "unable to find API Key" - } - ] - } - } - } - }, - "summary": "Retrieve a single api key.\nIf the API Key ID does not exist an HTTP 404 will be returned.", - "security": [ - { - "Authorization": [] - } - ] - }, - "put": { - "description": "A JSON request body with a \"name\" property is required.\nMost provide the list of all the scopes an api key should have.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n", - "operationId": "Update the name & scopes of an API Key", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "scopes": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/api_key_name_id_scopes" - }, - "examples": { - "application/json": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope", - "scopes": [ - "user.profile.read", - "user.profile.update" - ] - } - } - }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "expected JSON request body with 'name' property" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "404": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "unable to find API Key to update" - } - ] - } - } - } - }, - "summary": "A JSON request body with a \"name\" property is required.\nMost provide the list of all the scopes an api key should have.", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "**Revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are deleting.|", - "operationId": "Delete API keys", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "404": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "unable to find API Key" - } - ] - } - } - } - }, - "summary": "**Revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/scheduled_sends/{batch_id}": { - "parameters": [ - { - "name": "batch_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "patch": { - "description": "Update the status of a scheduled send.\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "operationId": "Update user scheduled send information", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status you would like the scheduled send to have.", - "enum": [ - "cancel", - "pause" - ] - } - }, - "required": [ - "status" - ] - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "status", - "message": "status must be either cancel or pause" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"\" : \"batch id not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] - } - } - } - }, - "summary": "Update the status of a scheduled send.", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "Delete the cancellation/pause of a scheduled send.\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "operationId": "Delete a cancellation or pause of a scheduled send", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] - } - } - } - }, - "summary": "Delete the cancellation/pause of a scheduled send.", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Get cancel/paused scheduled send information for a specific batch_id.\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "operationId": "Retrieve scheduled send", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "title": "Retrieve scheduled send response", - "items": { - "$ref": "#/definitions/user_scheduled_send_status" - } - }, - "examples": { - "application/json": [ - { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", - "status": "cancel" - }, - { - "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", - "status": "pause" - } - ] - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "Get cancel/paused scheduled send information. If {batch_id} is omitted, all of the user's scheduled send cancellations\na", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/scheduled_sends": { - "parameters": [], - "post": { - "description": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "operationId": "Cancel or pause a scheduled send", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "title": "Cancel or pause a scheduled send request", - "type": "object", - "properties": { - "batch_id": { - "type": "string", - "description": "The batch ID is the identifier that your scheduled mail sends share.", - "pattern": "^[a-zA-Z0-9]" - }, - "status": { - "type": "string", - "default": "pause", - "description": "The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}", - "enum": [ - "pause", - "cancel" - ] - } - }, - "required": [ - "batch_id", - "status" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/user_scheduled_send_status" - } - }, - "400": { - "description": "\"\" : \"max limit reached\"\n\"batch_id\" : \"invalid batch id\"\n\"batch_id\" : \"a status for this batch id exists, try PATCH to update the status\"", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "max limit reached" - }, - { - "field": "batch_id", - "message": "invalid batch id" - }, - { - "field": "batch_id", - "message": "a status for this batch id exists, try PATCH to update the status" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "Cancel or pause a scheduled send. If the maximum number of cancellations/pauses are added, HTTP 400 will\nbe returned.", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Get all cancel/paused scheduled send information.\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "operationId": "Get all scheduled sends", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/user_scheduled_send_status" - } - }, - "examples": { - "application/json": [ - { - "batch_id": "YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg", - "status": "cancel" - }, - { - "batch_id": "UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2", - "status": "cancel" - } - ] - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers/{subuser_name}": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", - "operationId": "Delete a subuser", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "This endpoint allows you to enable or disable a subuser.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", - "operationId": "Enable/disable a subuser", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not this subuser is disabled. True means disabled, False means enabled." - } - } - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid username" - }, - { - "message": "no fields provided" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "500": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "unable to enable user" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/assigned": { - "parameters": [], - "get": { - "description": "Retrieve a list of your IP addresses.", - "operationId": "List all assigned IPs", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "title": "List all assigned IPs response", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean" - }, - "start_date": { - "type": "integer" - } - } - } - }, - "examples": { - "application/json": [ - { - "ip": "167.89.21.3", - "pools": [ - "new_test5" - ], - "warmup": true, - "start_date": 1409616000 - } - ] - } - } - }, - "summary": "See only assigned IPs.", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/plain_content": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get plain content mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enabled": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update plain content mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enabled": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/campaigns/{campaign_id}/schedules": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "get": { - "description": "View the time that this campaign is scheduled to be sent. \n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "View Scheduled Time of a Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "View Scheduled Time of a Campaign response", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": [ - "send_at" - ] - }, - "examples": { - "application/json": { - "send_at": 1490778528 - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "Changes the send_at time for the specified campaign.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Update a Scheduled Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "title": "Update a Scheduled Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": [ - "send_at" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "title": "Update a Scheduled Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID" - }, - "send_at": { - "type": "integer", - "description": "The unix timestamp to send the campaign." - }, - "status": { - "type": "string", - "description": "The status of the schedule." - } - }, - "required": [ - "id", - "send_at", - "status" - ] - } - }, - "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" - } - ] - } - } - }, - "403": { - "description": "\"send_at\": \"You cannot update the send_at value of non-scheduled campaign.\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "send_at", - "message": "You cannot update the send_at value of non-scheduled campaign." - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "Changes the send_at time for the specified campaign.", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "A successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Unschedule a Scheduled Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "403": { - "description": "\"\": \"This campaign is already In Progress.\"\n\"\": \"This campaign is already Sent.\"\n\"\": \"This campaign is already Paused.\"\n\"\": \"This campaign is already Canceled.\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "This campaign is already In Progress." - }, - { - "field": null, - "message": "This campaign is already Sent." - }, - { - "field": null, - "message": "This campaign is already Paused." - }, - { - "field": null, - "message": "This campaign is already Canceled." - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "A successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Send your campaign at a specific date and time.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Schedule a Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "title": "Schedule a Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "description": "The unix timestamp for the date and time you would like your campaign to be sent out." - } - }, - "required": [ - "send_at" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "title": "Schedule a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID." - }, - "send_at": { - "type": "integer", - "description": "The date time you scheduled your campaign to be sent." - }, - "status": { - "type": "string", - "description": "The status of your campaign.", - "enum": [ - "Scheduled" - ] - } - }, - "required": [ - "id", - "send_at", - "status" - ] - }, - "examples": { - "application/json": { - "id": 1234, - "send_at": 1489771528, - "status": "Scheduled" - } - } - }, - "400": { - "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "403": { - "description": "\"\": \"You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH." - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/suppression/bounces/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "", - "operationId": "Get a Bounce", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer" - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string" - }, - "status": { - "type": "string" - } - } - } - }, - "examples": { - "application/json": [ - { - "created": 1443651125, - "email": "bounce1@test.com", - "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", - "status": "5.1.1" - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)", - "operationId": "Delete a bounce", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "email_address", - "in": "query", - "description": "The email address you would like to remove from the bounce list.", - "required": true, - "type": "string", - "format": "email" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/template": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get template mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "enabled": false, - "html_content": "

<% body %>Example

\n" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update template mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "enabled": false, - "html_content": "

<% body %>Example

\n" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/address_whitelist": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get address whitelist mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_address_whitelabel" - }, - "examples": { - "application/json": { - "enabled": false, - "list": [ - "example.com" - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update address whitelist mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "list": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_address_whitelabel" - }, - "examples": { - "application/json": { - "enabled": true, - "list": [ - "email1@example.com" - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/footer": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get footer mail settings [params can be null?]", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_footer" - }, - "examples": { - "application/json": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update footer mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/mail_settings_footer" - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_footer" - }, - "examples": { - "application/json": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/suppressions/global/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "", - "operationId": "Retrieve a Global Suppression", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "Retrieve a Global Suppression response", - "type": "object", - "properties": { - "recipient_email": { - "type": "string" - } - }, - "required": [ - "recipient_email" - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "", - "operationId": "Delete a Global Suppression", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "" - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/tracking_settings/google_analytics": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get Google Analytics Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update Google Analytics Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_source": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_term": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_campaign": { - "type": "string" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "utm_campaign": { - "type": "string" - }, - "utm_content": { - "type": "string" - }, - "utm_medium": { - "type": "string" - }, - "utm_source": { - "type": "string" - }, - "utm_term": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/partner_settings/new_relic": { - "parameters": [], - "patch": { - "description": "**This endpoint allows you to update or change your New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html).", - "operationId": "Updates New Relic partner settings.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "license_key": { - "type": "string", - "description": "The license key for your New Relic account." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this partner setting is enabled." - }, - "enable_subuser_statistics": { - "type": "boolean", - "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/partner_settings_new_relic" - }, - "examples": { - "application/json": { - "enable_subuser_statistics": true, - "enabled": true, - "license_key": "" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "**This endpoint allows you to retrieve your current New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html).", - "operationId": "Returns all New Relic partner settings.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/partner_settings_new_relic" - }, - "examples": { - "application/json": { - "enable_subuser_statistics": false, - "enabled": true, - "license_key": "" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/partner_settings": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve a list of all partner settings that you can enable.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html).", - "operationId": "Returns a list of all partner settings.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of settings to return per page.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The paging offset.", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the partner." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this partner setting has been enabled." - }, - "name": { - "type": "string", - "description": "The name of the partner setting." - }, - "description": { - "type": "string", - "description": "A description of this partner setting." - } - }, - "required": [ - "title", - "enabled", - "name", - "description" - ] - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "title": "Partner title", - "enabled": true, - "name": "partner_name", - "description": "A description of a partner." - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/spam_check": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update spam check mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "url": { - "type": "string" - }, - "max_score": { - "type": "integer" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_spam_check" - }, - "examples": { - "application/json": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get spam check mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_spam_check" - }, - "examples": { - "application/json": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/forward_spam": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update forward spam mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" - }, - "examples": { - "application/json": { - "email": "", - "enabled": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get forward spam mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" - }, - "examples": { - "application/json": { - "email": "", - "enabled": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/forward_bounce": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update forward bounce mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "email": { - "type": "string" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_bounce" - }, - "examples": { - "application/json": { - "email": "", - "enabled": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get forward bounce mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_bounce" - }, - "examples": { - "application/json": { - "enabled": false, - "email": null - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/categories": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get categories", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "type": "integer" - }, - { - "name": "sort_by", - "in": "query", - "type": "string" - }, - { - "name": "order", - "in": "query", - "type": "string" - }, - { - "name": "category", - "in": "query", - "type": "string" - }, - { - "name": "offset", - "in": "query", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "category": { - "type": "string" - } - } - } - }, - "examples": { - "application/json": [ - { - "category": "category 1" - }, - { - "category": "category 2" - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/account": { - "parameters": [], - "get": { - "description": "Your user's account information includes the user's account type and reputation.", - "operationId": "Get a user's account information.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "GET User Account response", - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of account for this user.", - "enum": [ - "free", - "paid" - ] - }, - "reputation": { - "type": "number", - "description": "The sender reputation for this user." - } - }, - "required": [ - "type", - "reputation" - ] - }, - "examples": { - "application/json": { - "reputation": 100, - "type": "paid" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get all mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string" - }, - "enabled": { - "type": "boolean" - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - } - } - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "title": "Address Whitelist", - "enabled": false, - "name": "address_whitelist", - "description": "Address / domains that should never have email suppressed." - }, - { - "title": "BCC", - "enabled": false, - "name": "bcc", - "description": "Automatically BCC an address for every e-mail sent." - }, - { - "title": "Bounce Purge", - "enabled": false, - "name": "bounce_purge", - "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days." - }, - { - "title": "Event Notification", - "enabled": true, - "name": "event_notify", - "description": "Controls notifications for events, such as bounces, clicks, and opens." - }, - { - "title": "Footer", - "enabled": false, - "name": "footer", - "description": "Allows you to add a custom footer to outgoing email." - }, - { - "title": "Forward Bounce", - "enabled": true, - "name": "forward_bounce", - "description": "Allows you to forward bounces to a specific email address." - }, - { - "title": "Forward Spam", - "enabled": false, - "name": "forward_spam", - "description": "Allows for a copy of spam reports to be forwarded to an email address." - }, - { - "title": "Legacy Email Template", - "enabled": true, - "name": "template", - "description": "Allows you to customize your outgoing HTML emails." - }, - { - "title": "Plain Content", - "enabled": false, - "name": "plain_content", - "description": "Convert your plain text emails to HTML." - }, - { - "title": "Spam Checker", - "enabled": true, - "name": "spam_check", - "description": "Check outbound messages for spam content." - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/ips": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve all of the IP whitelabels that have been createdy by this account.**\n\nYou may include a search key by using the \"ip\" parameter. This enables you to perform a prefix search for a given IP segment (e.g. \"192.\").\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", - "operationId": "Retrieve all IP whitelabels", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of results to retrieve.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list of results to begin retrieving IPs from.", - "type": "integer" - }, - { - "name": "ip", - "in": "query", - "description": "The IP segment that you would like to use in a prefix search.", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/ip_whitelabel" - } - }, - "examples": { - "application/json": [ - { - "id": 1, - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example.com", - "user_id": 8 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.1" - } - }, - { - "id": 2, - "ip": "192.168.1.2", - "rdns": "o2.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - }, - { - "username": "jane@example2.com", - "user_id": 9 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o2.email.example.com", - "data": "192.168.1.2" - } - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "**This endpoint allows you to create an IP whitelabel.**\n\nWhen creating an IP whitelable, you should use the same subdomain that you used when you created a domain whitelabel.\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", - "operationId": "Create an IP whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address that you want to whitelabel." - }, - "subdomain": { - "type": "string", - "description": "The subdomain that will be used to send emails from the IP. Should be the same as the subdomain used for your domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The root, or sending, domain that will be used to send message from the IP." - } - }, - "required": [ - "ip", - "subdomain", - "domain" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_whitelabel" - }, - "examples": { - "application/json": { - "id": 123, - "ip": "192.168.1.2", - "rdns": "o1.email.example.com", - "users": [], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.2" - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/segments/{segment_id}/recipients": { - "parameters": [ - { - "name": "segment_id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "get": { - "description": "List all of the recipients in a segment.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "List Recipients On a Segment", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "page", - "in": "query", - "type": "integer" - }, - { - "name": "page_size", - "in": "query", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "title": "List Recipients On a Segment response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_recipient" - } - } - }, - "required": [ - "recipients" - ] - }, - "examples": { - "application/json": { - "recipients": [ - { - "created_at": 1422313607, - "email": "jones@example.com", - "first_name": null, - "id": "YUBh", - "last_clicked": null, - "last_emailed": null, - "last_name": "Jones", - "last_opened": null, - "updated_at": 1422313790, - "custom_fields": [ - { - "id": 23, - "name": "pet", - "value": "Indiana", - "type": "text" - } - ] - } - ] - } - } - }, - "400": { - "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"" - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"" - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/suppression/bounces": { - "parameters": [], - "delete": { - "description": "Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete email addresses from your bounce list. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)\n\nNote: the 'delete_all' and 'emails' parameters should be used independently of each other as they have different purposes.", - "operationId": "Delete bounces", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "delete_all": { - "type": "boolean", - "description": "This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter." - }, - "emails": { - "type": "array", - "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.", - "items": { - "type": "string" - } - } - } - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Bounces are messages that are returned to the server that sent it. \n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)", - "operationId": "List all bounces", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", - "type": "number" - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when a bounce was created (inclusive).", - "type": "number" - }, - { - "name": "Allow", - "in": "header", - "description": "", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "number" - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string" - }, - "status": { - "type": "string" - } - } - } - }, - "examples": { - "application/json": [ - { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", - "status": "5.1.1" - }, - { - "created": 1250337600, - "email": "example@example.com", - "reason": "550 5.1.1 : Recipient address rejected: User unknown in virtual alias table ", - "status": "5.1.1" - } - ] - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers": { - "parameters": [], - "get": { - "description": "This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", - "operationId": "List all Subusers", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of this subuser.", - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "The number of results you would like to get in each request.", - "type": "number" - }, - { - "name": "offset", - "in": "query", - "description": "The number of subusers to skip.", - "type": "number" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/subuser" - } - }, - "examples": { - "application/json": [ - { - "disabled": false, - "email": "example@example.com", - "id": 1234, - "username": "example_subuser" - }, - { - "disabled": false, - "email": "example2@example.com", - "id": 1234, - "username": "example_subuser2" - } - ] - } - }, - "401": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", - "operationId": "Create Subuser", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username for this subuser." - }, - "email": { - "type": "string", - "description": "The email address of the subuser.", - "format": "email" - }, - "password": { - "type": "string", - "description": "The password this subuser will use when logging into SendGrid." - }, - "ips": { - "type": "array", - "description": "The IP addresses that should be assigned to this subuser.", - "items": { - "type": "string", - "format": "ipv4" - } - } - }, - "required": [ - "username", - "email", - "password", - "ips" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/subuser_post" - }, - "examples": { - "application/json": { - "username": "example_subuser", - "user_id": 1234, - "email": "example@example.com", - "signup_session_token": "", - "authorization_token": "", - "credit_allocation": { - "type": "unlimited" - } - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "username exists" - }, - { - "message": "unable to validate IPs at this time" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "403": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "you dont have permission to access this resource" - } - ] - } - } - }, - "500": { - "description": "", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "unable to validate IPs at this time" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/recipients/count": { - "parameters": [], - "get": { - "description": "Get a count of the current number of recipients in your contact database.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Get a Count of Recipients", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_recipient_count" - }, - "examples": { - "application/json": { - "recipient_count": 1234 - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/suppressions/global/{email_address}": { - "parameters": [ - { - "name": "email_address", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "Global Suppressions are email addresses that will not receive any emails.", - "operationId": "Check if a recipient address is in the global suppressions group.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "recipient_email": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "recipient_email": "test1@example.com" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/campaigns/{campaign_id}": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "delete": { - "description": "For more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Delete a Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"" - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "This is a place for notes and extra information about this endpoint. It is written\nin Markdown - more info in the [documentation](/docs/designer#markdown).\n\nThere are several special markdown helpers that automatically build tables\nand html off of your endpoint definition. You can find some examples in this content.\n\nClick the \"Open Editor\" button above to start editing this content.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Get a single campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/campaign_response" - }, - "examples": { - "application/json": { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Update a Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "title": "Update a Campaign request", - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the campaign." - }, - "subject": { - "type": "string", - "description": "The subject line for your campaign." - }, - "categories": { - "type": "array", - "description": "The categories you want to tag on this campaign.", - "items": { - "type": "string" - } - }, - "html_content": { - "type": "string", - "description": "The HTML content of this campaign." - }, - "plain_content": { - "type": "string", - "description": "The plain content of this campaign." - } - }, - "required": [ - "title", - "subject", - "categories", - "html_content", - "plain_content" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/campaign_response" - }, - "examples": { - "application/json": { - "id": 986724, - "title": "May Newsletter", - "subject": "New Products for Summer!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "summer line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our summer line!

", - "plain_content": "Check out our summer line!", - "status": "Draft" - } - } - }, - "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"", - "examples": { - "application/json": { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" - }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" - }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" - }, - { - "field": "sender_id", - "message": "sender_id does not exist" - }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" - }, - { - "field": "list_ids", - "message": "list_ids do not all exist" - }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" - }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" - }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" - }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "403": { - "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", - "schema": { - "type": "object", - "properties": {} - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "You may only update a campaign when it is in draft mode." - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/suppressions/global": { - "parameters": [], - "post": { - "description": "Global Suppressions are email addresses that will not receive any emails.", - "operationId": "Add recipient addresses to the global suppression group.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" - } - } - } - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "items": { - "type": "string" - } - } - } - }, - "examples": { - "application/json": { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/tracking_settings/subscription": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get Subscription Tracking Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "landing": { - "type": "string" - }, - "plain_content": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "url": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "enabled": true, - "html_content": "

Something something unsubscribe <% %> something something

\n", - "landing": "

subscribehere

\n", - "plain_content": "Something something unsubscribe <% %> something something", - "replace": "thetag", - "url": "" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update Subscription Tracking Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "landing": { - "type": "string" - }, - "url": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "landing": { - "type": "string" - }, - "url": { - "type": "string" - }, - "replace": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "enabled": true, - "landing": "landing page html", - "url": "url", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail/batch/{batch_id}": { - "parameters": [ - { - "name": "batch_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "Validate whether or not a batch id is valid.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", - "operationId": "Validate batch ID", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_batch_id" - }, - "examples": { - "application/json": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "invalid batch id" - } - ] - } - } - }, - "401": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "Validate whether or not a batch id is valid", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/profile": { - "parameters": [], - "patch": { - "description": "Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)\n\nIt should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH.", - "operationId": "Update a user's profile", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/user_profile" - } - }, - { - "name": "on-behalf-of", - "in": "header", - "description": "You can enter a subuser name as the value for this header, in order to update the subuser's profile.", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/user_profile" - }, - "examples": { - "application/json": { - "address": "814 West Chapman Avenue", - "address2": "", - "city": "Orange", - "company": "SendGrid", - "country": "US", - "first_name": "Example", - "last_name": "User", - "phone": "555-555-5555", - "state": "CA", - "website": "http://www.sendgrid.com", - "zip": "92868" - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", - "operationId": "Get a user's profile", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "GET User Profile response", - "type": "object", - "properties": { - "address": { - "type": "string", - "description": "The user's address." - }, - "address2": { - "type": "string", - "description": "The second line of the user's address." - }, - "city": { - "type": "string", - "description": "The user's city." - }, - "company": { - "type": "string", - "description": "The name of the user's company." - }, - "country": { - "type": "string", - "description": "The user's country." - }, - "first_name": { - "type": "string", - "description": "The user's first name." - }, - "last_name": { - "type": "string", - "description": "The user's last name." - }, - "phone": { - "type": "string", - "description": "The user's phone number." - }, - "state": { - "type": "string", - "description": "The user's state." - }, - "website": { - "type": "string", - "description": "The user's website URL." - }, - "zip": { - "type": "string", - "description": "The user's zip code." - } - }, - "required": [ - "address", - "city", - "company", - "country", - "first_name", - "last_name", - "phone", - "state", - "website", - "zip" - ] - }, - "examples": { - "application/json": { - "address": "814 West Chapman Avenue", - "address2": "", - "city": "Orange", - "company": "SendGrid", - "country": "US", - "first_name": "Test", - "last_name": "User", - "phone": "555-555-5555", - "state": "CA", - "website": "http://www.sendgrid.com", - "zip": "92868" - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/campaigns/{campaign_id}/schedules/test": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "post": { - "description": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Send a Test Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "to": { - "type": "string", - "description": "The email address that should receive the test campaign.", - "format": "email" - } - }, - "required": [ - "to" - ] - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "title": "Send a Test Campaign request", - "type": "object", - "properties": { - "to": { - "type": "string" - } - }, - "required": [ - "to" - ] - } - }, - "400": { - "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"to\": \"Please provide an email address to which the test should be sent.\"\n\"to\": \"You can only send tests to 10 addresses at a time.\"\n\"subject\": \"Please add a subject to your campaign before sending a test.\"\n\"plain_content\": \"Plain content and html content can't both be blank. Please set one of these values before sending a test.\"\n\"sender_id\": \"Please assign a sender identity to your campaign before sending a test.\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "To send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips": { - "parameters": [], - "get": { - "description": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabel info.\nThe start_date field corresponds to when warmup started for that IP.", - "operationId": "List all IPs", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "ip", - "in": "query", - "description": "The IP address to get", - "type": "string" - }, - { - "name": "exclude_whitelabels", - "in": "query", - "description": "Should we exclude whitelabels?", - "type": "boolean" - }, - { - "name": "subuser", - "in": "query", - "description": "The subuser you are requesting for.", - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "The number of IPs you want returned at the same time.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The offset for the number of IPs that you are requesting.", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "subusers": { - "type": "array", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean" - }, - "start_date": { - "type": [ - "number", - "null" - ] - }, - "whitelabeled": { - "type": "boolean" - } - } - } - }, - "examples": { - "application/json": [ - { - "ip": "127.0.0.1", - "subusers": [ - "example_subuser1", - "example_subuser2" - ], - "rdns": "o1.em.example.com", - "pools": [], - "warmup": true, - "start_date": 1250337600, - "whitelabeled": true - }, - { - "ip": "127.0.0.1", - "subusers": [], - "pools": [], - "warmup": false, - "start_date": null, - "whitelabeled": false - } - ] - } - } - }, - "summary": "See a list of all assigned and unassigned IPs.\nResponse includes warm up status, pools, assigned subusers, and whitelabe", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/links/default": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve the default link whitelabel.**\n\nDefault link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order:\n
    \n
  • Validated link whitelabels marked as \"default\"
    • \n
  • Legacy link whitelabels (migrated from the whitelabel wizard)
    • \n
  • Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net)
    • \n
\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Retrieve a Default Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "domain", - "in": "query", - "description": "The domain to match against when finding a corresponding link whitelabel.", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/link_whitelabel" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - }, - "summary": "Default link is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, th", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/tracking_settings": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get Tracking Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "title": { - "type": "string" - }, - "description": { - "type": "string" - }, - "enabled": { - "type": "boolean" - } - } - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "name": "open", - "title": "Open Tracking", - "description": "lorem ipsum... .", - "enabled": true - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/tracking_settings/click": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get Click Track Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enable_text": { - "type": "boolean" - }, - "enabled": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enable_text": false, - "enabled": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update Click Tracking Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enable_text": { - "type": "boolean" - }, - "enabled": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enable_text": false, - "enabled": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/clients/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve your email statistics segmented by client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", - "operationId": "Retrieve email statistics by client type.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - }, - "examples": { - "application/json": [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] - } - ] - } - } - }, - "summary": "Gets email statistics by client type.", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/templates/{template_id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The id of the transactional template you want to delete.", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "**This endpoint allows you to delete a transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", - "operationId": "Delete a template.", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "**This endpoint allows you to edit a transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", - "operationId": "Edit a transactional template.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the transactional template.", - "maxLength": 100 - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/transactional_template" - }, - "examples": { - "application/json": { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "new_example_name", - "versions": [] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "**This endpoint allows you to retrieve a single transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", - "operationId": "Retrieve a single transactional template.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/transactional_template" - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/bcc": { - "parameters": [], - "get": { - "description": "", - "operationId": "Get BCC mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_bcc" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "enabled": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "description": "", - "operationId": "Update BCC mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/mail_settings::patch" - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings::patch" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "enabled": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/pools": { - "parameters": [], - "post": { - "description": "", - "operationId": "Create an IP pool.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_pool" - }, - "examples": { - "application/json": { - "name": "marketing" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "List all IP pools.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/ip_pool" - } - }, - "examples": { - "application/json": [ - { - "name": "marketing" - }, - { - "name": "transactional" - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/recipients/billable_count": { - "parameters": [], - "get": { - "description": "You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Get the count of billable recipients", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_recipient_count" - }, - "examples": { - "application/json": { - "recipient_count": 1234 - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/warmup": { - "parameters": [], - "post": { - "description": "", - "operationId": "Add an IP to warmup.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "start_date": { - "type": "integer" - } - } - } - }, - "examples": { - "application/json": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get all IPs that are currently warming up.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_warmup_response" - }, - "examples": { - "application/json": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/templates": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve all transactional templates.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).", - "operationId": "Retrieve all transactional templates.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/transactional_template" - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "**This endpoint allows you to create a transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).", - "operationId": "Create a transactional template.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name for the new transactional template.", - "maxLength": 100 - } - }, - "required": [ - "name" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/transactional_template" - }, - "examples": { - "application/json": { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "example_name", - "versions": [] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/groups/{group_id}/suppressions": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The id of the suppression group that you are retrieving email addresses from.", - "required": true, - "type": "string" - } - ], - "get": { - "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": "Retrieve all suppressions for a suppression group", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "string" - } - }, - "examples": { - "application/json": [ - "example@example.com", - "example2@example.com" - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "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": "Add suppressions to a suppression group", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "description": "The email address that you want to add to the unsubscribe group.", - "items": { - "type": "string" - } - } - }, - "required": [ - "recipient_emails" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "description": "The email address that were added to the suppressions list.", - "items": { - "type": "string" - } - } - } - }, - "examples": { - "application/json": { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/groups": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve a list of all suppression groups created by this user.**\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": "Retrieve all suppression groups associated with the user.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/suppression_group_unsubscribes" - } - }, - "examples": { - "application/json": [ - { - "id": 1234, - "name": "Unsubscribe Group", - "description": "An Unsubscribe Group", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 1234 - }, - { - "id": 1234, - "name": "Unsubscribe Group", - "description": "An Unsubscribe Group", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 1234 - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "**This endoint 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": "Create a Group", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "title": "Create a Group request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the new suppression group. May not share its name with any other suppression group on the user.", - "maxLength": 30 - }, - "description": { - "type": "string", - "description": "A description of the suppression group.", - "maxLength": 100 - }, - "is_default": { - "type": "boolean", - "default": "false", - "description": "Indicates if this is the default suppression group." - } - }, - "required": [ - "name", - "description" - ] - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/suppression_group" - }, - "examples": { - "application/json": { - "id": 1234, - "name": "A group name", - "description": "A group description", - "last_email_sent_at": null, - "is_default": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/groups/{group_id}/suppressions/{email}": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The id of the suppression group that you are removing an email address from.", - "required": true, - "type": "string" - }, - { - "name": "email", - "in": "path", - "description": "The email address that you want to remove from the suppression group.", - "required": true, - "type": "string" - } - ], - "delete": { - "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 a suppression from a suppression group", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/warmup/{ip_address}": { - "parameters": [ - { - "name": "ip_address", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "", - "operationId": "Remove an IP from warmup.", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get warmup status for a particular IP.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_warmup_response" - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/reserved_fields": { - "parameters": [], - "get": { - "description": "List fields that are reserved and can't be used for custom field names. [GET]\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "operationId": "Get reserved custom fields fields.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "title": "List fields that are reserved and can't be used for custom field names. response", - "type": "object", - "properties": { - "reserved_fields": { - "type": "array", - "description": "The reserved fields that are already set up within custom fields.", - "items": { - "$ref": "#/definitions/contactdb_custom_field" - } - } - }, - "required": [ - "reserved_fields" - ] - }, - "examples": { - "application/json": { - "reserved_fields": [ - { - "name": "first_name", - "type": "text" - }, - { - "name": "last_name", - "type": "text" - }, - { - "name": "email", - "type": "text" - }, - { - "name": "created_at", - "type": "date" - }, - { - "name": "updated_at", - "type": "date" - }, - { - "name": "last_emailed", - "type": "date" - }, - { - "name": "last_clicked", - "type": "date" - }, - { - "name": "last_opened", - "type": "date" - }, - { - "name": "my_custom_field", - "type": "text" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/campaigns": { - "parameters": [], - "get": { - "description": "Returns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Get all Campaigns", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of results you would like to receive at a time.", - "type": "number" - }, - { - "name": "offset", - "in": "query", - "description": "The index of the first campaign to return, where 0 is the first campaign.", - "type": "number" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "items": { - "$ref": "#/definitions/campaign_response" - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

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

Last call for winter clothes!

", - "plain_content": "Last call for winter clothes!", - "status": "Sent" - } - ] - } - } - } - }, - "summary": "Returns campaigns in reverse order they were created (newest first)\nReturns an empty array if no campaigns exist", - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "description": "Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\n\nNote: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Create a Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/campaign_request" - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/campaign_response" - }, - "examples": { - "application/json": { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - } - }, - "400": { - "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\": \"You've reached your limit of 250 campaigns. Please delete one or more and try again.\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" - }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" - }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" - }, - { - "field": "sender_id", - "message": "sender_id does not exist" - }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" - }, - { - "field": "list_ids", - "message": "list_ids do not all exist" - }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" - }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" - }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" - }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "{% info %}\nA campaign requires a title to be created.\nIn order to send or schedule the campaign, you will be required to", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers/reputations": { - "parameters": [], - "get": { - "description": "Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will effect your sender rating.\n\nThis endpoint allows you to request the reputations for your subusers.", - "operationId": "Retrieve Subuser Reputations", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "usernames", - "in": "query", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "reputation": { - "type": "number", - "description": "The sender reputation this subuser has attained." - }, - "username": { - "type": "string", - "description": "The subuser that has this reputation.f" - } - }, - "required": [ - "reputation", - "username" - ] - } - }, - "examples": { - "application/json": [ - { - "username": "example_subuser", - "reputation": 99 - }, - { - "username": "example_subuser2", - "reputation": 95.2 - } - ] - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/ips/{id}": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The id of the IP whitelabel that you would like to retrieve.", - "required": true, - "type": "string" - } - ], - "get": { - "description": "**This endpoint allows you to retrieve an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", - "operationId": "Retrieve an IP whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_whitelabel" - }, - "examples": { - "application/json": { - "id": 123, - "ip": "192.168.1.1", - "rdns": "o1.email.example.com", - "users": [ - { - "username": "john@example.com", - "user_id": 7 - } - ], - "subdomain": "email", - "domain": "example.com", - "valid": true, - "legacy": false, - "a_record": { - "valid": true, - "type": "a", - "host": "o1.email.example.com", - "data": "192.168.1.1" - } - } - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The errors preventing the retrieval of the IP whitelabel.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message explaining why the IP whitelabel could not be found." - } - }, - "required": [ - "message" - ] - } - } - }, - "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Whitelabel ip not found." - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "description": "**This endpoint allows you to delete an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", - "operationId": "Delete an IP whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The errors preventing the IP whitelabel from being deleted.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message explaining why the IP whitelabel could not be deleted." - } - } - } - } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Whitelabel ip not found." - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/bounce_purge": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update bounce purge mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "hard_bounces": { - "type": "integer" - }, - "soft_bounces": { - "type": "integer" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" - }, - "examples": { - "application/json": { - "enabled": false, - "hard_bounces": null, - "soft_bounces": null - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get bounce purge mail settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" - }, - "examples": { - "application/json": { - "enabled": false, - "soft_bounces": 1234, - "hard_bounces": null - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/links": { - "parameters": [], - "post": { - "description": "**This endpoint allows you to create a new link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Create a Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Number of domains to return.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset.", - "type": "integer" - }, - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "domain": { - "type": "string", - "description": "The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address." - }, - "subdomain": { - "type": "string", - "description": "The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel." - }, - "default": { - "type": "boolean", - "description": "Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.", - "enum": [ - true, - false - ] - } - }, - "required": [ - "domain", - "subdomain" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/link_whitelabel" - }, - "examples": { - "application/json": { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": false, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "**This endpoint allows you to retrieve all link whitelabels.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Retrieve all link whitelabels", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "type": "integer" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/link_whitelabel" - } - }, - "examples": { - "application/json": [ - { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "default": true, - "valid": true, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "mail.example.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": true, - "type": "cname", - "host": "7.example.com", - "data": "sendgrid.net" - } - } - }, - { - "id": 2, - "domain": "example2.com", - "subdomain": "news", - "username": "john@example.com", - "user_id": 8, - "default": false, - "valid": false, - "legacy": false, - "dns": { - "domain_cname": { - "valid": true, - "type": "cname", - "host": "news.example2.com", - "data": "sendgrid.net" - }, - "owner_cname": { - "valid": false, - "type": "cname", - "host": "8.example2.com", - "data": "sendgrid.net" - } - } - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/settings/enforced_tls": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Change the Enforced TLS settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { - "type": "boolean" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "require_tls": true, - "require_valid_cert": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Get the current Enforced TLS settings.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "require_tls": { - "type": "boolean" - }, - "require_valid_cert": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "require_tls": false, - "require_valid_cert": false - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail/batch": { - "parameters": [], - "post": { - "description": "Generate a new Batch ID to associate with scheduled sends via the mail/send endpoint.\n\nIf you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", - "operationId": "Create a batch ID", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_batch_id" - }, - "examples": { - "application/json": { - "batch_id": "YOUR_BATCH_ID" - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "Generate a new Batch ID to associate with scheduled sends", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers/{subuser_name}/ips": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "put": { - "description": "Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html)\n* [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html)", - "operationId": "Update IPs assigned to a subuser", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "ips": { - "type": "array", - "items": { - "type": "string", - "format": "ipv4" - } - } - } - }, - "examples": { - "application/json": { - "ips": [ - "127.0.0.1" - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "" - } - }, - "/api_keys": { - "parameters": [], - "get": { - "description": "The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).", - "operationId": "List all API Keys belonging to the authenticated user", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "_isOpen": true, - "items": { - "$ref": "#/definitions/api_key_name_id" - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "**List all API Keys belonging to the authenticated user**\n\nThe API Keys feature allows customers to be able to generate ", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "**This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer |ID of the domain whitelabel to validate. |", - "operationId": "Validate a domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the domain whitelabel." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "validation_resuts": { - "type": "object", - "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", - "properties": { - "mail_cname": { - "type": "object", - "description": "The CNAME record for the domain whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this DNS record is valid." - }, - "reason": { - "type": "string", - "description": "The reason this record is invalid." - } - } - }, - "dkim1": { - "type": "object", - "description": "A DNS record for this domain whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid." - }, - "reason": { - "type": "null" - } - } - }, - "dkim2": { - "type": "object", - "description": "A DNS record for this whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid." - }, - "reason": { - "type": "null" - } - } - }, - "spf": { - "type": "object", - "description": "The SPF record for the whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - }, - "reason": { - "type": "null" - } - } - } - } - } - } - }, - "examples": { - "application/json": { - "id": 1, - "valid": true, - "validation_resuts": { - "mail_cname": { - "valid": false, - "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\"." - }, - "dkim1": { - "valid": true, - "reason": null - }, - "dkim2": { - "valid": true, - "reason": null - }, - "spf": { - "valid": true, - "reason": null - } - } - } - } - }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object", - "properties": {} - } - }, - "500": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message explaining the reason for the error." - } - }, - "required": [ - "message" - ] - } - } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting TXT" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/devices/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", - "operationId": "Retrieve email statistics by device type.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today.", - "required": false, - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "How many results to include on each page.", - "required": false, - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "How many results to exclude.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string" - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve.", - "required": true, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - }, - "examples": { - "application/json": [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 1, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 2, - "unique_opens": 2 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/scopes": { - "parameters": [], - "get": { - "description": "**This endpoint returns a list of all scopes that this user has access to.**\n\nAPI Keys can be used to authenticate the use of [SendGrid’s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). ", - "operationId": "Returns a list of scopes for which this user has access.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The list of scopes for which this user has access.", - "uniqueItems": true, - "items": { - "type": "string" - } - } - }, - "required": [ - "scopes" - ] - }, - "examples": { - "application/json": { - "scopes": [ - "mail.send", - "alerts.create", - "alerts.read" - ] - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "null", - "description": "This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required." - }, - "message": { - "type": "string", - "description": "Explains why the scopes cannot be returned." - } - }, - "required": [ - "message" - ] - } - } - }, - "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/geo/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve your email statistics segmented by country and state/province.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", - "operationId": "Retrieve email statistics by country and state/province.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "How many results to include on each page.", - "required": false, - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "How many results to exclude.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How you would like the statistics to be grouped. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. ", - "required": false, - "type": "string" - }, - { - "name": "country", - "in": "query", - "description": "The country you would like to see statistics for. Currently only supported for US and CA.", - "required": false, - "type": "string", - "enum": [ - "US", - "CA" - ] - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_country" - } - }, - "examples": { - "application/json": [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 1, - "unique_clicks": 0, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - } - ] - } - } - }, - "summary": "" - } - }, - "/whitelabel/domains": { - "parameters": [], - "post": { - "description": "**This endpoint allows you to create a whitelabel for one of your domains.**\n\nIf you are creating a domain whitelabel that you would like a subuser to use, you have two options:\n1. Use the \"username\" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel.\n2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel.\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", - "operationId": "Create a domain whitelabel.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "domain": { - "type": "string", - "description": "Domain being whitelabeled." - }, - "subdomain": { - "type": "string", - "description": "The subdomain to use for this domain whitelabel." - }, - "username": { - "type": "string", - "description": "The username that this whitelabel will be associated with." - }, - "ips": { - "type": "array", - "description": "The IP addresses that will be included in the custom SPF record for this whitelabel.", - "items": { - "type": "string" - } - }, - "custom_spf": { - "type": "boolean", - "description": "Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security." - }, - "default": { - "type": "boolean", - "description": "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain." - }, - "automatic_security": { - "type": "boolean", - "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation." - } - }, - "required": [ - "domain", - "subdomain" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel::domain" - }, - "examples": { - "application/json": { - "id": 302183, - "user_id": 1446226, - "subdomain": "example", - "domain": "example.com", - "username": "mbernier", - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_cname": { - "valid": false, - "type": "cname", - "host": "example.example.com", - "data": "u1446226.wl.sendgrid.net" - }, - "dkim1": { - "valid": false, - "type": "cname", - "host": "s1._domainkey.example.com", - "data": "s1.domainkey.u1446226.wl.sendgrid.net" - }, - "dkim2": { - "valid": false, - "type": "cname", - "host": "s2._domainkey.example.com", - "data": "s2.domainkey.u1446226.wl.sendgrid.net" - } - } - } - } - } - }, - "summary": "When creating a whitelabel for a subuser, there are two options available:\n Use the \"username\" parameter. This allows", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "**This endpoint allows you to retrieve a list of all domain whitelabels you have created.**\n\nA domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n", - "operationId": "List all domain whitelabels.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Number of domains to return.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset.", - "type": "integer" - }, - { - "name": "exclude_subusers", - "in": "query", - "description": "Exclude subuser domains from the result.", - "type": "boolean" - }, - { - "name": "username", - "in": "query", - "description": "The username associated with a whitelabel.", - "type": "string" - }, - { - "name": "domain", - "in": "query", - "description": "Search for domain whitelabels that match the given domain.", - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the domain whitelabel." - }, - "user_id": { - "type": "number", - "description": "The ID of the user that this whitelabel will be associated with." - }, - "subdomain": { - "type": "string", - "description": "The subdomain created for this domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel was created for." - }, - "username": { - "type": "string", - "description": "The username that this whitelabel is associated with." - }, - "ips": { - "type": "array", - "description": "The IPs that will be included in the custom SPF record.", - "items": { - "type": "string" - } - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates if this whitelabel has custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this whitelabel has been set as the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this is whitelabel was created with the legacy whitelabel tool." - }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel or not." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel that are used for authenticating the sending domain.", - "properties": { - "mail_server": { - "type": "object", - "description": "Designates which mail server is responsible for accepting messages from a domain.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record with no conflicts." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain sending the messages." - }, - "data": { - "type": "string", - "description": "The mail server responsible for accepting messages." - } - } - }, - "subdomain_spf": { - "type": "object", - "description": "The SPF record for the subdomain used to create this whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "host": { - "type": "string", - "description": "The domain that this SPF record will be used to authenticate." - }, - "data": { - "type": "string", - "description": "The SPF record." - } - } - }, - "dkim": { - "type": "object", - "description": "The DNS record used when creating the DKIM signature.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this DNS record is valid." - }, - "type": { - "type": "string", - "description": "The type of DNS record.", - "enum": [ - "cname", - "mx", - "txt" - ] - }, - "host": { - "type": "string", - "description": "The domain that these DNS records will be applied to.", - "format": "hostname" - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } - } - } - } - }, - "required": [ - "id", - "user_id", - "subdomain", - "domain", - "username", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ] - } - }, - "examples": { - "application/json": [ - { - "id": 1, - "domain": "example.com", - "subdomain": "mail", - "username": "john@example.com", - "user_id": 7, - "ips": [ - "192.168.1.1", - "192.168.1.2" - ], - "custom_spf": true, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": true, - "dns": { - "mail_cname": { - "host": "mail.example.com", - "type": "cname", - "data": "u7.wl.sendgrid.net", - "valid": true - }, - "spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:u7.wl.sendgrid.net -all", - "valid": true - }, - "dkim1": { - "host": "s1._domainkey.example.com", - "type": "cname", - "data": "s1._domainkey.u7.wl.sendgrid.net", - "valid": true - }, - "dkim2": { - "host": "s2._domainkey.example.com", - "type": "cname", - "data": "s2._domainkey.u7.wl.sendgrid.net", - "valid": true - } - } - }, - { - "id": 2, - "domain": "example2.com", - "subdomain": "news", - "username": "jane@example2.com", - "user_id": 8, - "ips": [], - "custom_spf": false, - "default": true, - "legacy": false, - "automatic_security": true, - "valid": false, - "dns": { - "mail_server": { - "host": "news.example2.com", - "type": "mx", - "data": "sendgrid.net", - "valid": false - }, - "subdomain_spf": { - "host": "news.example2.com", - "type": "txt", - "data": "v=spf1 include:sendgrid.net ~all", - "valid": false - }, - "domain_spf": { - "host": "example2.com", - "type": "txt", - "data": "v=spf1 include:news.example2.com -all", - "valid": false - }, - "dkim": { - "host": "example2.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false - } - } - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/campaigns/{campaign_id}/schedules/now": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "post": { - "description": "Send your campaign right now. Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, we don't need a body.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "operationId": "Send a Campaign", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "201": { - "description": "", - "schema": { - "title": "Send a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "status": { - "type": "string" - } - }, - "required": [ - "id", - "status" - ] - }, - "examples": { - "application/json": { - "id": 1234, - "status": "Scheduled" - } - } - }, - "400": { - "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "403": { - "description": "\"\": \"You may only send a campaign when it is in draft mode.\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "You may only send a campaign when it is in draft mode." - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/webhooks/parse/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve the statistics for your Parse Webhook useage.**\n\nSendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments.\n\nThere are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries).", - "operationId": "Retrieves Inbound Parse Webhook statistics.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of statistics to return on each page.", - "required": false, - "type": "string" - }, - { - "name": "offset", - "in": "query", - "description": "The number of statistics to skip.", - "required": false, - "type": "string" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How you would like the statistics to by grouped. ", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", - "required": false, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the stats were collected." - }, - "stats": { - "type": "array", - "description": "The Parse Webhook usage statistics.", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "received": { - "type": "number", - "description": "The number of emails received and parsed by the Parse Webhook." - } - }, - "required": [ - "received" - ] - } - } - } - } - }, - "required": [ - "date", - "stats" - ] - } - }, - "examples": { - "application/json": [ - { - "date": "2015-10-11", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-29", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-30", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - }, - { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/clients/{client_type}/stats": { - "parameters": [ - { - "name": "client_type", - "in": "path", - "description": "Specifies the type of client to retrieve stats for. Must be either \"phone\", \"tablet\", \"webmail\", or \"desktop\".", - "required": true, - "type": "string", - "enum": [ - "phone", - "tablet", - "webmail", - "desktop" - ] - } - ], - "get": { - "description": "**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Client Types\n- phone\n- tablet\n- webmail\n- desktop\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", - "operationId": "Retrieve stats by a specific client type.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - }, - "examples": { - "application/json": [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] - } - ] - } - } - }, - "summary": "Gets email statistics by a single client type.", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/browsers/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve your email statistics segmented by browser type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", - "operationId": "Retrieve email statistics by browser. ", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today.", - "required": false, - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "The number of results to include on each page.", - "required": false, - "type": "string" - }, - { - "name": "offset", - "in": "query", - "description": "The number of results to exclude.", - "required": false, - "type": "string" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the stats. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, - { - "name": "browsers", - "in": "query", - "description": "The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times.", - "required": false, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_clicks" - } - }, - "examples": { - "application/json": [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "clicks": 0, - "unique_clicks": 0 - }, - "name": "Chrome", - "type": "browser" - }, - { - "metrics": { - "clicks": 1, - "unique_clicks": 1 - }, - "name": "Firefox", - "type": "browser" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "clicks": 0, - "unique_clicks": 0 - }, - "name": "Chrome", - "type": "browser" - }, - { - "metrics": { - "clicks": 1, - "unique_clicks": 1 - }, - "name": "Firefox", - "type": "browser" - } - ] - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers/stats/sums": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**\n\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", - "operationId": " Retrieve the totals for each email statistic metric for all subusers.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort. ", - "required": false, - "type": "string", - "enum": [ - "desc", - "asc" - ] - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "required": false, - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results from.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Must be a single metric.", - "required": false, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/category_stats" - }, - "examples": { - "application/json": { - "date": "2015-10-11", - "stats": [] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/subusers/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve the email statistics for the given subusers.**\n\nYou may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser.\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", - "operationId": "Retrieve email statistics for your subusers.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "required": false, - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results from.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, - { - "name": "subusers", - "in": "query", - "description": "The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers.", - "required": true, - "type": "string" - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today.", - "required": false, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/stats" - }, - "examples": { - "application/json": [ - { - "date": "2015-10-01", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-02", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-03", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-04", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-05", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-06", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-07", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-08", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-09", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-10-10", - "stats": [ - { - "type": "subuser", - "name": "Matt_subuser", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/links/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "description": "The id of the link whitelabel that you want to validate.", - "required": true, - "type": "integer" - } - ], - "post": { - "description": "**This endpoint allows you to validate a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", - "operationId": "Validate a Link Whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the link whitelabel." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the link whitelabel is valid.", - "enum": [ - true, - false - ] - }, - "validation_results": { - "type": "object", - "description": "The individual validations results for each of the DNS records associated with this link whitelabel.", - "required": [ - "domain_cname" - ], - "properties": { - "domain_cname": { - "type": "object", - "description": "The DNS record generated for the sending domain used for this link whitelabel.", - "required": [ - "valid", - "reason" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this DNS record is valid.", - "enum": [ - true, - false - ] - }, - "reason": { - "type": [ - "string", - "null" - ], - "description": "Null if the DNS record is valid. If the DNS record is invalid, this will explain why." - } - } - }, - "owner_cname": { - "type": "object", - "description": "The DNS record created to verify the link whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [ - true, - false - ] - }, - "reason": { - "type": [ - "null", - "string" - ], - "description": "Null if valid. If the DNS record is invalid, this will explain why." - } - }, - "required": [ - "valid", - "reason" - ] - } - } - } - }, - "required": [ - "id", - "valid", - "validation_results" - ] - }, - "examples": { - "application/json": { - "id": 1, - "valid": true, - "validation_results": { - "domain_cname": { - "valid": false, - "reason": "Expected CNAME to match \"sendgrid.net.\" but found \"example.com.\"." - }, - "owner_cname": { - "valid": true, - "reason": null - } - } - } - } - }, - "400": { - "description": "Unexpected error in API call. See HTTP response body for details." - }, - "500": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The reasons why the validation failed.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "The reason why the link whitelabel could not be validated." - } - }, - "required": [ - "message" - ] - } - } - }, - "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting CNAME" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/pools/{pool_name}/ips/{ip}": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "ip", - "in": "path", - "required": true, - "type": "string" - } - ], - "delete": { - "description": "", - "operationId": "Remove an IP address from a pool.", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/{ip_address}": { - "parameters": [ - { - "name": "ip_address", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "description": "", - "operationId": "See which pools an IP address belongs to.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "subusers": { - "type": "array", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean" - }, - "start_date": { - "type": [ - "integer", - "null" - ] - }, - "whitelabeled": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "ip": "000.00.00.0", - "subusers": [ - "subuser1", - "subuser2" - ], - "rdns": "o1.em.example.com", - "pools": [ - "test1" - ], - "warmup": false, - "start_date": null, - "whitelabeled": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/pools/{pool_name}/ips": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "post": { - "description": "", - "operationId": "Add an IP to a pool", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string" - } - } - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "pools": { - "type": "array", - "items": { - "type": "string" - } - }, - "start_date": { - "type": "integer" - }, - "warmup": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "ip": "000.00.00.0", - "pools": [ - "test1" - ], - "start_date": 1409616000, - "warmup": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/api_key": { - "parameters": [], - "post": { - "description": "This will create a new random API Key for the user. A JSON request body containing a \"name\" property is required. If number of maximum keys is reached, HTTP 403 will be returned.\n\nThere is a limit of 100 API Keys on your account.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\nSee the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes.", - "operationId": "Create API keys", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name you will use to describe this API Key." - }, - "scopes": { - "type": "array", - "description": "The individual permissions that you are giving to this API Key.", - "items": { - "type": "string" - } - } - }, - "required": [ - "name" - ] - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/definitions/api_key_name_id_scopes" - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "name", - "message": "missing required argument" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "403": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "Cannot create more than 100 API Keys" - } - ] - } - } - } - }, - "summary": "**Generate a new API Key for the authenticated user**\n\nThis will create a new random API Key for the user. A JSON reques", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/categories/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve all of your email statistics for each of your categories.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). ", - "operationId": "Retrieve Email Statistics for Categories", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "categories", - "in": "query", - "description": "The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.", - "required": true, - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "The number of results to include.", - "required": false, - "type": "integer", - "maximum": 500 - }, - { - "name": "offset", - "in": "query", - "description": "The number of results to skip.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/category_stats" - } - }, - "examples": { - "application/json": [ - { - "date": "2015-10-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/stats": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve all of your global email statistics between a given date range.**\n\nParent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats.", - "operationId": "Retrieve global email statistics", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of results to return.", - "required": false, - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the stats were gathered." - }, - "stats": { - "type": "array", - "description": "The individual email activity stats.", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered. " - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - } - } - } - } - } - }, - "required": [ - "date", - "stats" - ] - } - }, - "examples": { - "application/json": [ - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/categories/stats/sums": { - "parameters": [], - "get": { - "description": "**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.\n\nCategories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). ", - "operationId": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Must be a single metric.", - "required": false, - "type": "string" - }, - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort.", - "required": false, - "type": "string", - "enum": [ - "desc", - "asc" - ] - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned.", - "required": false, - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "": { - "$ref": "#/definitions/category_stats" - } - } - }, - "examples": { - "application/json": { - "date": "2015-01-01", - "stats": [ - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 20, - "deferred": 0, - "delivered": 20, - "invalid_emails": 0, - "opens": 20, - "processed": 0, - "requests": 20, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 20, - "unique_opens": 20, - "unsubscribe_drops": 0, - "unsubscribes": 20 - }, - "name": "cat1", - "type": "category" - }, - { - "metrics": { - "blocks": 1, - "bounce_drops": 0, - "bounces": 0, - "clicks": 19, - "deferred": 0, - "delivered": 19, - "invalid_emails": 0, - "opens": 19, - "processed": 0, - "requests": 20, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 19, - "unique_opens": 19, - "unsubscribe_drops": 0, - "unsubscribes": 19 - }, - "name": "cat2", - "type": "category" - }, - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 5, - "deferred": 0, - "delivered": 5, - "invalid_emails": 0, - "opens": 5, - "processed": 0, - "requests": 5, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 5, - "unique_opens": 5, - "unsubscribe_drops": 0, - "unsubscribes": 5 - }, - "name": "cat3", - "type": "category" - }, - { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 6, - "deferred": 0, - "delivered": 5, - "invalid_emails": 0, - "opens": 6, - "processed": 0, - "requests": 5, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 5, - "unique_opens": 5, - "unsubscribe_drops": 0, - "unsubscribes": 6 - }, - "name": "cat4", - "type": "category" - }, - { - "metrics": { - "blocks": 10, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 10, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "cat5", - "type": "category" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/webhooks/event/settings": { - "parameters": [], - "patch": { - "description": "", - "operationId": "Update Event Notification Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "url": { - "type": "string" - }, - "group_resubscribe": { - "type": "boolean" - }, - "delivered": { - "type": "boolean" - }, - "group_unsubscribe": { - "type": "boolean" - }, - "spamreport": { - "type": "boolean" - }, - "bounce": { - "type": "boolean" - }, - "deferred": { - "type": "boolean" - }, - "unsubscribe": { - "type": "boolean" - }, - "processed": { - "type": "boolean" - }, - "open": { - "type": "boolean" - }, - "click": { - "type": "boolean" - }, - "dropped": { - "type": "boolean" - } - } - } - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "url": { - "type": "string" - }, - "group_resubscribe": { - "type": "boolean" - }, - "delivered": { - "type": "boolean" - }, - "group_unsubscribe": { - "type": "boolean" - }, - "spamreport": { - "type": "boolean" - }, - "bounce": { - "type": "boolean" - }, - "deferred": { - "type": "boolean" - }, - "unsubscribe": { - "type": "boolean" - }, - "processed": { - "type": "boolean" - }, - "open": { - "type": "boolean" - }, - "click": { - "type": "boolean" - }, - "dropped": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enabled": true, - "url": "url", - "group_resubscribe": true, - "delivered": true, - "group_unsubscribe": true, - "spamreport": true, - "bounce": true, - "deferred": true, - "unsubscribe": true, - "processed": true, - "open": true, - "click": true, - "dropped": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "description": "", - "operationId": "Retrieve Event Webhook Settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "url": { - "type": "string" - }, - "group_resubscribe": { - "type": "boolean" - }, - "delivered": { - "type": "boolean" - }, - "group_unsubscribe": { - "type": "boolean" - }, - "spam_report": { - "type": "boolean" - }, - "bounce": { - "type": "boolean" - }, - "deferred": { - "type": "boolean" - }, - "unsubscribe": { - "type": "boolean" - }, - "processed": { - "type": "boolean" - }, - "open": { - "type": "boolean" - }, - "click": { - "type": "boolean" - }, - "dropped": { - "type": "boolean" - } - } - }, - "examples": { - "application/json": { - "enabled": true, - "url": "url", - "group_resubscribe": true, - "delivered": true, - "group_unsubscribe": true, - "spam_report": true, - "bounce": true, - "deferred": true, - "unsubscribe": true, - "processed": true, - "open": true, - "click": true, - "dropped": true - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/webhooks/event/test": { - "parameters": [], - "post": { - "description": "", - "operationId": "Test Event Notification Settings ", - "consumes": [ - "application/json" - ], - "produces": [], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "url": { - "type": "string" - } - } - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/webhooks/parse/settings": { - "parameters": [], - "get": { - "description": "", - "operationId": "Retrieve Parse API settings", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "hostname": { - "type": "string" - }, - "url": { - "type": "string" - }, - "spam_check": { - "type": "boolean" - }, - "send_raw": { - "type": "boolean" - } - } - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "hostname": "example.com", - "url": "http://example.com/example", - "spam_check": false, - "send_raw": false - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/ips/{id}/validate": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "integer" - } - ], - "post": { - "description": "**This endpoint allows you to validate an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", - "operationId": "Validate an IP whitelabel", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the IP whitelabel." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the IP whitelabel is valid.", - "enum": [ - true, - false - ] - }, - "validation_results": { - "type": "object", - "description": "The specific results of the validation.", - "properties": { - "a_record": { - "type": "object", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the IP whitelabel could be validated.", - "enum": [ - true, - false - ] - }, - "reason": { - "type": [ - "null", - "string" - ], - "description": "The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated." - } - }, - "required": [ - "valid", - "reason" - ] - } - } - } - }, - "required": [ - "id", - "valid", - "validation_results" - ] - }, - "examples": { - "application/json": { - "id": 1, - "valid": true, - "validation_results": { - "a_record": { - "valid": true, - "reason": null - } - } - } - } - }, - "404": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The error messages for the failed validation.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message describing why the IP could not be validated." - } - }, - "required": [ - "message" - ] - } - } - }, - "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Whitelabel ip not found." - } - ] - } - } - }, - "500": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The error messages for the failed validation.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message describing why the IP whitelabel could not be validated." - } - }, - "required": [ - "message" - ] - } - } - }, - "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting rDNS" - } - ] - } - } - } - }, - "summary": "", - "security": [ - { - "Authorization": [] - } - ] - } - } - }, - "definitions": { - "contacts": { - "type": "object", - "properties": { - "address": { - "type": "string" - }, - "address2": {}, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "email": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" - }, - "zip": { - "type": "string" - } - } - }, - "subuser": { - "title": "List all Subusers for a parent response", - "type": "object", - "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not the user is enabled or disabled." - }, - "id": { - "type": "number", - "description": "The ID of this subuser." - }, - "username": { - "type": "string", - "description": "The name by which this subuser will be referred." - }, - "email": { - "type": "string", - "description": "The email address to contact this subuser.", - "format": "email" - } - }, - "required": [ - "disabled", - "id", - "username", - "email" - ] - }, - "contactdb_segments_conditions": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "value": { - "type": "string" - }, - "operator": { - "type": "string", - "enum": [ - "eq", - "ne", - "lt", - "gt", - "contains" - ] - }, - "and_or": { - "type": "string", - "enum": [ - "and", - "or", - "" - ] - } - }, - "required": [ - "field", - "value", - "operator" - ] - }, - "subuser_post": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the subuser." - }, - "user_id": { - "type": "number", - "description": "The user ID for this subuser." - }, - "email": { - "type": "string", - "description": "The email address for this subuser.", - "format": "email" - }, - "signup_session_token": { - "type": "string" - }, - "authorization_token": { - "type": "string" - }, - "credit_allocation": { - "type": "object", - "properties": { - "type": { - "type": "string" - } - } - } - }, - "required": [ - "username", - "user_id", - "email" - ] - }, - "contactdb_segments": { - "title": "Create a Segment request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of this segment." - }, - "list_id": { - "type": "integer", - "description": "The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list." - }, - "conditions": { - "type": "array", - "description": "The conditions for a recipient to be included in this segment.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" - } - }, - "recipient_count": { - "type": "number", - "description": "The count of recipients in this list. This is not included on creation of segments." - } - }, - "required": [ - "name", - "conditions" - ] - }, - "campaign_request": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." - }, - "subject": { - "type": [ - "string", - "null" - ], - "description": "The subject of your campaign that your recipients will see." - }, - "sender_id": { - "type": [ - "null", - "integer" - ], - "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails." - }, - "list_ids": { - "type": [ - "array", - "null" - ], - "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", - "items": { - "type": "integer" - } - }, - "segment_ids": { - "type": [ - "array", - "null" - ], - "description": "The segment IDs that you are sending this list to. You can have both segment IDs and list IDs.", - "items": { - "type": "integer" - } - }, - "categories": { - "type": [ - "array", - "null" - ], - "description": "The categories you would like associated to this campaign.", - "items": { - "type": "string" - } - }, - "suppression_group_id": { - "type": [ - "null", - "integer" - ], - "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type." - }, - "custom_unsubscribe_url": { - "type": [ - "string", - "null" - ], - "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups." - }, - "ip_pool": { - "type": [ - "string", - "null" - ], - "description": "The pool of IPs that you would like to send this email from." - }, - "html_content": { - "type": [ - "string", - "null" - ], - "description": "The HTML of your marketing email." - }, - "plain_content": { - "type": [ - "string", - "null" - ], - "description": "The plain text content of your emails." - } - }, - "required": [ - "title" - ] - }, - "contactdb_recipient_response": { - "type": "object", - "properties": { - "error_count": { - "type": "number", - "default": "0", - "description": "The number of errors found while adding recipients." - }, - "error_indices": { - "type": "array", - "default": "[]", - "description": "The indices of the recipient(s) sent that caused the error. ", - "items": { - "type": "number" - } - }, - "new_count": { - "type": "number", - "default": "0", - "description": "The count of new recipients added to the contactdb." - }, - "persisted_recipients": { - "type": "array", - "default": "[]", - "description": "The recipient IDs of the recipients that already existed from this request.", - "items": { - "type": "string" - } - }, - "updated_count": { - "type": "number", - "default": "0", - "description": "The recipients who were updated from this request." - }, - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_indices": { - "type": "array", - "items": { - "type": "number" - } - } - } - } - } - }, - "required": [ - "error_count", - "new_count", - "persisted_recipients", - "updated_count" - ] - }, - "transactional_template_version": { - "type": "object", - "properties": { - "template_id": { - "type": "string", - "description": "The name of the original transactional template." - }, - "active": { - "type": "integer", - "description": "Set the new version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active.", - "enum": [ - 0, - 1 - ] - }, - "name": { - "type": "string", - "description": "Name of the new transactional template version." - }, - "html_content": { - "type": "string", - "description": "The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." - }, - "plain_content": { - "type": "string", - "description": "Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." - }, - "subject": { - "type": "string", - "description": "Subject of the new transactional template version. Must include <%subject%> tag." - } - }, - "required": [ - "template_id", - "active", - "name", - "html_content", - "plain_content", - "subject" - ] - }, - "api_key_name_id_scopes": { - "allOf": [ - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The permissions this API Key has access to.", - "items": { - "type": "string" - } - } - } - }, - { - "$ref": "#/definitions/api_key_name_id" - } - ] - }, - "credentials": { - "type": "object", - "properties": { - "permissions": { - "type": "object", - "properties": { - "api": { - "type": "string" - }, - "mail": { - "type": "string" - }, - "web": { - "type": "string" - } - } - }, - "username": { - "type": "string" - } - } - }, - "partner_settings_new_relic": { - "type": "object", - "properties": { - "enable_subuser_statistics": { - "type": "boolean", - "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this setting is enabled. " - }, - "license_key": { - "type": "string", - "description": "The license key provided with your New Relic account." - } - }, - "required": [ - "enabled", - "license_key" - ] - }, - "suppression_group_unsubscribes": { - "type": "object", - "allOf": [ - { - "$ref": "#/definitions/suppression_group" - }, - { - "type": "object", - "required": [ - "unsubscribes" - ], - "properties": { - "unsubscribes": { - "type": "integer", - "description": "The unsubscribes associated with this group." - } - } - } - ] - }, - "mail_settings_forward_bounce": { - "type": "object", - "properties": { - "email": { - "type": [ - "string", - "null" - ] - }, - "enabled": { - "type": "boolean" - } - } - }, - "api_key_name_id": { - "type": "object", - "properties": { - "api_key_id": { - "type": "string", - "description": "The ID of your API Key. " - }, - "name": { - "type": "string", - "description": "The name of your API Key." - } - } - }, - "monitor": { - "title": "Create monitor settings request", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address to send emails at the frequency specified for monitoring.", - "format": "email" - }, - "frequency": { - "type": "number", - "description": "The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. " - } - }, - "required": [ - "email", - "frequency" - ] - }, - "global:id": { - "type": "integer" - }, - "mail_settings_template": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - } - }, - "mail_settings_spam_check": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "max_score": { - "type": "integer" - }, - "url": { - "type": "string" - } - } - }, - "mail_settings_forward_spam": { - "type": "object", - "properties": { - "email": { - "type": [ - "string", - "null" - ] - }, - "enabled": { - "type": "boolean" - } - } - }, - "mail_settings::patch": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "email": { - "type": "string" - } - } - }, - "mail_settings_bounce_purge": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "soft_bounces": { - "type": [ - "integer", - "null" - ] - }, - "hard_bounces": { - "type": [ - "integer", - "null" - ] - } - } - }, - "mail_settings_bcc": { - "type": "object", - "properties": { - "email": { - "type": "string" - }, - "enabled": { - "type": "boolean" - } - } - }, - "mail_settings_address_whitelabel": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "list": { - "type": "array", - "items": { - "type": "string" - } - } - } - }, - "global:empty_request": { - "type": "null" - }, - "mail_batch_id": { - "type": "object", - "properties": { - "batch_id": { - "type": "string", - "pattern": "^[a-zA-Z0-9\\-\\_]" - } - }, - "required": [ - "batch_id" - ] - }, - "campaign_response": { - "allOf": [ - { - "$ref": "#/definitions/campaign_request" - }, - { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status of your campaign." - }, - "id": { - "type": "integer" - } - }, - "required": [ - "status" - ] - } - ] - }, - "contactdb_segments_with_id": { - "allOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the segment." - } - }, - "required": [ - "id" - ] - }, - { - "$ref": "#/definitions/contactdb_segments" - } - ] - }, - "contactdb_custom_field_with_id_value": { - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field_with_id" - }, - { - "type": "object", - "properties": { - "value": { - "type": [ - "string", - "null" - ], - "description": "The value of this recipient's custom field" - } - } - } - ], - "title": "ContactDB Custom field schema." - }, - "contactdb_custom_field_with_id": { - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field" - }, - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the custom field." - } - } - } - ], - "title": "ContactDB Custom field schema with ID." - }, - "contactdb_custom_field": { - "title": "ContactDB Custom field schema.", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the field" - }, - "type": { - "type": "string", - "description": "The type of the field.", - "enum": [ - "date", - "text", - "number" - ] - } - } - }, - "contactdb_recipient_count": { - "type": "object", - "properties": { - "recipient_count": { - "type": "number", - "description": "The count of recipients." - } - }, - "required": [ - "recipient_count" - ] - }, - "mail_settings_footer": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - }, - "plain_content": { - "type": "string" - } - } - }, - "user_scheduled_send_status": { - "allOf": [ - { - "$ref": "#/definitions/mail_batch_id" - }, - { - "type": "object", - "description": "The status of the scheduled send.", - "properties": { - "status": { - "type": "string", - "description": "The status of the scheduled send.", - "enum": [ - "cancel", - "pause" - ] - } - }, - "required": [ - "status" - ] - } - ] - }, - "contactdb_list": { - "title": "ContactDB lists", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The reference ID of your list." - }, - "name": { - "type": "string", - "description": "The name of your list." - }, - "recipient_count": { - "type": "integer", - "description": "The count of recipients currently in the list." - } - }, - "required": [ - "id", - "name", - "recipient_count" - ] - }, - "user_profile": { - "type": "object", - "properties": { - "address": { - "type": "string" - }, - "address2": { - "type": "string" - }, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" - }, - "website": { - "type": "string" - }, - "zip": { - "type": "string" - } - } - }, - "global:ErrorResponse": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": [ - "string", - "null" - ], - "description": "The field that generated the error." - }, - "message": { - "type": "string", - "description": "The error message." - } - }, - "required": [ - "message" - ] - } - } - } - }, - "suppression_bounce": { - "type": "object", - "properties": { - "created": { - "type": "number", - "description": "The unix timestamp for when the bounce record was created at SendGrid." - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string", - "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." - }, - "status": { - "type": "string", - "description": "Enhanced SMTP bounce response" - } - } - }, - "contactdb_recipient": { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of this recipient." - }, - "created_at": { - "type": "number", - "description": "The time this record was created in your contactdb, in unixtime." - }, - "custom_fields": { - "type": "array", - "description": "The custom fields assigned to this recipient and their values.", - "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id_value" - } - }, - "email": { - "type": "string", - "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", - "format": "email" - }, - "first_name": { - "type": [ - "string", - "null" - ], - "description": "The first name of this recipient. This is a default custom field that SendGrid provides." - }, - "last_name": { - "type": [ - "string", - "null" - ], - "description": "The last name of the recipient." - }, - "last_clicked": { - "type": [ - "number", - "null" - ], - "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime." - }, - "last_emailed": { - "type": [ - "number", - "null" - ], - "description": "The last time this user was emailed by one of your campaigns, in unixtime." - }, - "last_opened": { - "type": [ - "number", - "null" - ], - "description": "The last time this recipient opened an email from you, in unixtime." - }, - "updated_at": { - "type": "number", - "description": "The last update date for this recipient's record." - } - }, - "required": [ - "email" - ] - } - } - } - }, - "whitelabel::domain": { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the domain whitelabel." - }, - "user_id": { - "type": "number", - "description": "The ID of the user that this whitelabel will be associated with." - }, - "subdomain": { - "type": "string", - "description": "The subdomain to use for this domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel is being created for." - }, - "username": { - "type": "string", - "description": "The username that this whitelabel will be associated with." - }, - "ips": { - "type": "array", - "description": "The IPs to be included in the custom SPF record for this domain whitelabel.", - "items": { - "type": "object", - "properties": {} - } - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates whether this domain whitelabel will use custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this domain whitelabel is the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this domain whitelabel was created using the legacy whitelabel tool." - }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this domain whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel that are used to authenticate the sending domain.", - "required": [ - "mail_cname", - "dkim1", - "dkim2" - ], - "properties": { - "mail_cname": { - "type": "object", - "description": "The CNAME for your sending domain that points to sendgrid.net.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid CNAME." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this CNAME is created for.", - "format": "hostname" - }, - "data": { - "type": "string", - "description": "The CNAME record." - } - } - }, - "dkim1": { - "type": "object", - "description": "A DNS record.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this DNS record was created for." - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } - }, - "dkim2": { - "type": "object", - "description": "A DNS record.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this DNS record was created for." - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } - } - } - } - }, - "required": [ - "id", - "user_id", - "subdomain", - "domain", - "username", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ] - }, - "whitelabel:domain_spf": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel was created for." - }, - "subdomain": { - "type": "string", - "description": "The subdomain that was used to create this whitelabel." - }, - "username": { - "type": "string", - "description": "The username of the account that this whitelabel is associated with." - }, - "user_id": { - "type": "integer", - "description": "The user_id of the account that this whitelabel is associated with." - }, - "ips": { - "type": "array", - "description": "The IP addresses that are included in the SPF record for this whitelabel.", - "items": {} - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates if this whitelabel uses custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this is the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." - }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel.", - "required": [ - "mail_server", - "subdomain_spf", - "domain_spf", - "dkim" - ], - "properties": { - "mail_server": { - "type": "object", - "description": "Designates which mail server is responsible for accepting messages from a domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain sending the messages." - }, - "type": { - "type": "string", - "description": "They type of DNS record." - }, - "data": { - "type": "string", - "description": "The mail server responsible for accepting messages from the sending domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - } - } - }, - "subdomain_spf": { - "type": "object", - "description": "The SPF record for the subdomain used to create this whitelabel.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid SPF record." - } - } - }, - "domain_spf": { - "type": "object", - "description": "The SPF record for the root domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The root domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - } - } - }, - "dkim": { - "type": "object", - "description": "The DKIM record for messages sent using this whitelabel.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The DNS labels for the DKIM signature." - }, - "type": { - "type": "string", - "description": "The type of data in the DKIM record." - }, - "data": { - "type": "string", - "description": "The DKIM record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the DKIM record is valid." - } - } - } - } - } - }, - "required": [ - "id", - "domain", - "subdomain", - "username", - "user_id", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ] - }, - "transactional_template": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the transactional template." - }, - "name": { - "type": "string", - "description": "The name for the transactional template.", - "maxLength": 100 - }, - "versions": { - "type": "array", - "description": "The different versions of this transactional template.", - "items": { - "$ref": "#/definitions/transactional_template_version" - } - } - }, - "required": [ - "id", - "name" - ] - }, - "suppression_group": { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The id of the suppression group." - }, - "name": { - "type": "string", - "description": "The name of the suppression group. Each group created by a user must have a unique name.", - "maxLength": 30 - }, - "description": { - "type": "string", - "description": "A description of the suppression group.", - "maxLength": 100 - }, - "last_email_sent_at": { - "type": "null" - }, - "is_default": { - "type": "boolean", - "default": "false", - "description": "Indicates if this is the default suppression group." - } - }, - "required": [ - "id", - "name", - "description" - ] - }, - "advanced_stats_country": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "opens", - "unique_clicks", - "unique_opens" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - }, - "advanced_stats_opens": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "opens", - "unique_opens" - ], - "properties": { - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - }, - "advanced_stats_clicks": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "unique_clicks" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - }, - "advanced_stats_mailbox_provider": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "opens", - "unique_clicks", - "unique_opens", - "blocks", - "bounces", - "deferred", - "delivered", - "drops", - "spam_reports" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered." - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "drops": { - "type": "integer", - "description": "The number of emails that were not delivered due to the recipient email address being on a suppression list." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - }, - "stats": { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their statistics.", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered. " - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - } - } - } - } - } - } - } - }, - "link_whitelabel": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the link whitelabel." - }, - "domain": { - "type": "string", - "description": "The root domain for this link whitelabel." - }, - "subdomain": { - "type": "string", - "description": "The subdomain used to generate the DNS records for this link whitelabel. This subdomain must be different from the subdomain used for your domain whitelabel." - }, - "username": { - "type": "string", - "description": "The username of the account that this link whitelabel is associated with." - }, - "user_id": { - "type": "integer", - "description": "The id of the user that this whitelabel is associated with." - }, - "default": { - "type": "boolean", - "description": "Indicates if this is the default link whitelabel.", - "enum": [ - true, - false - ] - }, - "valid": { - "type": "boolean", - "description": "Indicates if this link whitelabel is valid.", - "enum": [ - true, - false - ] - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this link whitelabel was created using the legacy whitelabel tool.", - "enum": [ - true, - false - ] - }, - "dns": { - "type": "object", - "description": "The DNS records generated for this link whitelabel.", - "required": [ - "domain_cname" - ], - "properties": { - "domain_cname": { - "type": "object", - "description": "The DNS record generated to point to your link whitelabel subdomain.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [ - true, - false - ] - }, - "type": { - "type": "string", - "description": "The type of DNS record that was generate.", - "enum": [ - "cname", - "txt", - "mx" - ] - }, - "host": { - "type": "string", - "description": "The domain that this whitelabel will use when whitelabeling the links in your email.", - "format": "hostname" - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to.", - "format": "hostname" - } - } - }, - "owner_cname": { - "type": "object", - "description": "The DNS record generated to verify who created the link whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [ - true, - false - ] - }, - "type": { - "type": "string", - "description": "The type of DNS record generated.", - "enum": [ - "cname", - "txt", - "mx" - ] - }, - "host": { - "type": "string", - "description": "Used to verify the link whitelabel. The subdomain of this domain is the user id of the user who created the link whitelabel.", - "format": "hostname" - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to.", - "format": "hostname" - } - }, - "required": [ - "valid", - "host", - "data" - ] - } - } - } - }, - "required": [ - "id", - "domain", - "subdomain", - "username", - "user_id", - "default", - "valid", - "legacy", - "dns" - ] - }, - "ip_warmup_response": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string" - }, - "start_date": { - "type": "integer" - } - } - } - }, - "ip_pool": { - "type": "object", - "properties": { - "name": { - "type": "string" - } - } - }, - "category_stats": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the statistics were gathered." - }, - "stats": { - "type": "array", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered." - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - }, - "required": [ - "blocks", - "bounce_drops", - "bounces", - "clicks", - "deferred", - "delivered", - "invalid_emails", - "opens", - "processed", - "requests", - "spam_report_drops", - "spam_reports", - "unique_clicks", - "unique_opens", - "unsubscribe_drops", - "unsubscribes" - ] - }, - "name": { - "type": "string", - "description": "The name of the category." - }, - "type": { - "type": "string", - "description": "How you are segmenting your statistics." - } - }, - "required": [ - "type" - ] - } - } - }, - "required": [ - "date" - ] - }, - "ip_whitelabel": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the IP whitelabel." - }, - "ip": { - "type": "string", - "description": "The IP address that this whitelabel was created for." - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for the IP address. This points to the IP whitelabel subdomain." - }, - "users": { - "type": "array", - "description": "The users who are able to send mail from the IP.", - "items": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the user who can send mail from this IP." - }, - "user_id": { - "type": "integer", - "description": "The ID of the user who can send mail from this IP." - } - }, - "required": [ - "username", - "user_id" - ] - } - }, - "subdomain": { - "type": "string", - "description": "The subdomain created for this IP whitelabel. This is where the rDNS record points." - }, - "domain": { - "type": "string", - "description": "The root, or sending, domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." - }, - "a_record": { - "type": "object", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the a_record is valid." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "This is the web address that will be mapped to the IP address." - }, - "data": { - "type": "string", - "description": "The IP address being whitelabeled." - } - } - } - }, - "required": [ - "id", - "ip", - "rdns", - "users", - "subdomain", - "domain", - "valid", - "legacy", - "a_record" - ] - } - }, - "securityDefinitions": { - "Authorization": { - "name": "Authorization", - "type": "apiKey", - "in": "header" - } - } -} \ No newline at end of file