From 4b605839b24075e4eed7993dc4fd90822a41ce9c Mon Sep 17 00:00:00 2001 From: Carly Vanderwert Date: Fri, 25 Jun 2021 10:07:01 -0600 Subject: [PATCH] Adding new Stoplight oai file for a docs change (#84) * Overwrite files with exports from Stoplight classic * Add missing stats definition * uploading new stoplight file for docs change * Update .travis.yml Co-authored-by: Wade Christensen Co-authored-by: Samuel Mendes --- .travis.yml | 1 + oai.json | 49484 ++++++++++++++++++++++++++----------------- oai.yaml | 38394 ++++++++++++++++++++------------- oai_stoplight.json | 8065 ++++++- 4 files changed, 61919 insertions(+), 34025 deletions(-) diff --git a/.travis.yml b/.travis.yml index 58f60fb..6a0d0eb 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,6 +3,7 @@ install: - pip install prance flex script: - python test/test.py +- prance validate --strict oai_stoplight.json notifications: slack: if: branch = main diff --git a/oai.json b/oai.json index 41acc0b..8163c53 100644 --- a/oai.json +++ b/oai.json @@ -1,15 +1,20 @@ { "swagger": "2.0", "info": { - "version": "3.0", - "title": "SendGrid v3 API Documentation", - "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" + "version": "", + "title": "Email Activity (beta)", + "description": "The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data. The Beta endpoints for the new Email Activity APIs - functionality is subject to change without notice. You may not have access to this Beta endpoint.\n\nEmail Activity offers filtering and search by event type for two days worth of data. There is an optional add-on to store 60 days worth of data. This add-on also gives you access to the ability to download a CSV of the 60 days worth of email event data." }, "host": "api.sendgrid.com", "basePath": "/v3", "schemes": [ - "http", - "https" + "http" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" ], "securityDefinitions": { "Authorization": { @@ -26,13 +31,7 @@ "tags": [ "Mail Send" ], - "description": "This endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n* Top level parameters are referred to as \"global\".\n* Individual fields within the personalizations array will override any other global, or “message level”, parameters that are defined outside of personalizations.\n \n**SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages: [C#](https://github.com/sendgrid/sendgrid-csharp), [Go](https://github.com/sendgrid/sendgrid-go), [Java](https://github.com/sendgrid/sendgrid-java), [Node JS](https://github.com/sendgrid/sendgrid-nodejs), [PHP](https://github.com/sendgrid/sendgrid-php), [Python](https://github.com/sendgrid/sendgrid-python), and [Ruby](https://github.com/sendgrid/sendgrid-ruby).**\n\n\nFor more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "description": "The Mail Send endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## Helper Libraries\n\nTwilio SendGrid provides libraries to help you quickly and easily integrate with the v3 Web API in 7 different languages:\n* [C#](https://github.com/sendgrid/sendgrid-csharp)\n* [Go](https://github.com/sendgrid/sendgrid-go)\n* [Java](https://github.com/sendgrid/sendgrid-java)\n* [Node JS](https://github.com/sendgrid/sendgrid-nodejs)\n* [PHP](https://github.com/sendgrid/sendgrid-php)\n* [Python](https://github.com/sendgrid/sendgrid-python)\n* [Ruby](https://github.com/sendgrid/sendgrid-ruby)\n\n## Dynamic Transactional Templates and Handlebars\n\nIn order to send a dynamic template, specify the template ID with the `template_id` parameter. \n\nTo specify handlebar substitutions, define your substitutions in the request JSON with this syntax:\n\n```\n\"dynamic_template_data\": {\n      \"guest\": \"Jane Doe\",\n      \"partysize\": \"4\",\n      \"english\": true,\n      \"date\": \"April 1st, 2021\"\n    }\n```\n\nFor more information about Dynamic Transactional Templates and Handlebars, see our documentation and reference pages.\n\n* [How to send an email with Dynamic Transactional Templates\n](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/)\n* [Using Handlebars](https://sendgrid.com/docs/for-developers/sending-email/using-handlebars/) \n\n## Mail body compression\n\nMail body compression is available to some high volume accounts. Talk to your CSM if you are interested in this functionality. Mail body compression works by setting up a JSON payload as defined on this page, then compressing it with gzip (the gzip file can be no more than 30mb).\n\nTo use mail body compression:\n1. Add a `Content-Encoding` header, with a value of `gzip`. \n a. `Content-Encoding: gzip` \n2. Send the gzip as a data-binary. \n a. `--data-binary '@data.json.gz'\n`", "parameters": [ { "name": "body", @@ -42,58 +41,60 @@ "properties": { "personalizations": { "type": "array", - "description": "An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled.", + "description": "An array of messages and their metadata. Each object within personalizations can be thought of as an envelope - it defines who should receive an individual message and how that message should be handled. See our [Personalizations documentation](https://sendgrid.com/docs/for-developers/sending-email/personalizations/) for examples.", "uniqueItems": false, "maxItems": 1000, "items": { "type": "object", "properties": { + "from": { + "$ref": "#/definitions/from_email_object" + }, "to": { - "type": "array", - "description": "An array of recipients. Each object within this array may contain the name, but must always contain the email, of a recipient.", - "minItems": 1, - "maxItems": 1000, - "items": { - "$ref": "#/definitions/email_object" - } + "$ref": "#/definitions/to_email_array" }, "cc": { "type": "array", - "description": "An array of recipients who will receive a copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.", + "description": "An array of recipients who will receive a copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recpient's name.", "maxItems": 1000, "items": { - "$ref": "#/definitions/email_object" + "$ref": "#/definitions/cc_bcc_email_object" } }, "bcc": { "type": "array", - "description": "An array of recipients who will receive a blind carbon copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.", + "description": "An array of recipients who will receive a blind carbon copy of your email. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recpient's name.", "maxItems": 1000, "items": { - "$ref": "#/definitions/email_object" + "$ref": "#/definitions/cc_bcc_email_object" } }, "subject": { "type": "string", - "description": "The subject of your email. Char length requirements, according to the RFC - http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310", + "description": "The subject of your email. See character length requirements according to [RFC 2822](http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310).", "minLength": 1 }, "headers": { "type": "object", - "description": "A collection of JSON key/value pairs allowing you to specify specific handling instructions for your email. You may not overwrite the following headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC" + "description": "A collection of JSON key/value pairs allowing you to specify handling instructions for your email. You may not overwrite the following headers: `x-sg-id`, `x-sg-eid`, `received`, `dkim-signature`, `Content-Type`, `Content-Transfer-Encoding`, `To`, `From`, `Subject`, `Reply-To`, `CC`, `BCC`" }, "substitutions": { "type": "object", - "description": "A collection of key/value pairs following the pattern \"substitution_tag\":\"value to substitute\". All are assumed to be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters.", + "description": "Substitutions allow you to insert data without using Dynamic Transactional Templates. This field should **not** be used in combination with a Dynamic Transactional Template, which can be identified by a `template_id` starting with `d-`. This field is a collection of key/value pairs following the pattern \"substitution_tag\":\"value to substitute\". The key/value pairs must be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters. The total collective size of your substitutions may not exceed 10,000 bytes per personalization object.", "maxProperties": 10000 }, + "dynamic_template_data": { + "type": "object", + "description": "Dynamic template data is available using Handlebars syntax in Dynamic Transactional Templates. This field should be used in combination with a Dynamic Transactional Template, which can be identified by a `template_id` starting with `d-`. This field is a collection of key/value pairs following the pattern \"variable_name\":\"value to insert\"." + }, "custom_args": { "type": "object", - "description": "Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. May not exceed 10,000 bytes." + "description": "Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This field may not exceed 10,000 bytes.", + "maxProperties": 10000 }, "send_at": { "type": "integer", - "description": "A unix timestamp allowing you to specify when you want your email to be delivered. Scheduling more than 72 hours in advance is forbidden." + "description": "A unix timestamp allowing you to specify when your email should be delivered. Scheduling delivery more than 72 hours in advance is forbidden." } }, "required": [ @@ -102,30 +103,30 @@ } }, "from": { - "$ref": "#/definitions/email_object" + "$ref": "#/definitions/from_email_object" }, "reply_to": { - "$ref": "#/definitions/email_object" + "$ref": "#/definitions/reply_to_email_object" }, "subject": { "type": "string", - "description": "The global, or “message level”, subject of your email. This may be overridden by personalizations[x].subject.", + "description": "The global or 'message level' subject of your email. This may be overridden by subject lines set in personalizations.", "minLength": 1 }, "content": { "type": "array", - "description": "An array in which you may specify the content of your email. You can include multiple mime types of content, but you must specify at least one mime type. To include more than one mime type, simply add another object to the array containing the `type` and `value` parameters.", + "description": "An array where you can specify the content of your email. You can include multiple [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of content, but you must specify at least one MIME type. To include more than one MIME type, add another object to the array containing the `type` and `value` parameters.", "items": { "type": "object", "properties": { "type": { "type": "string", - "description": "The mime type of the content you are including in your email. For example, “text/plain” or “text/html”.", + "description": "The MIME type of the content you are including in your email (e.g., `“text/plain”` or `“text/html”`).", "minLength": 1 }, "value": { "type": "string", - "description": "The actual content of the specified mime type that you are including in your email.", + "description": "The actual content of the specified MIME type that you are including in your email.", "minLength": 1 } }, @@ -137,7 +138,7 @@ }, "attachments": { "type": "array", - "description": "An array of objects in which you can specify any attachments you want to include.", + "description": "An array of objects where you can specify any attachments you want to include.", "items": { "type": "object", "properties": { @@ -148,17 +149,17 @@ }, "type": { "type": "string", - "description": "The mime type of the content you are attaching. For example, “text/plain” or “text/html”.", + "description": "The MIME type of the content you are attaching (e.g., `“text/plain”` or `“text/html”`).", "minLength": 1 }, "filename": { "type": "string", - "description": "The filename of the attachment." + "description": "The attachment's filename." }, "disposition": { "type": "string", "default": "attachment", - "description": "The content-disposition of the attachment specifying how you would like the attachment to be displayed. For example, “inline” results in the attached file being displayed automatically within the message while “attachment” results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file).", + "description": "The attachment's content-disposition, specifying how you would like the attachment to be displayed. For example, `“inline”` results in the attached file are displayed automatically within the message while `“attachment”` results in the attached file require some action to be taken before it is displayed, such as opening or downloading the file.", "enum": [ "inline", "attachment" @@ -166,7 +167,7 @@ }, "content_id": { "type": "string", - "description": "The content id for the attachment. This is used when the disposition is set to “inline” and the attachment is an image, allowing the file to be displayed within the body of your email." + "description": "The attachment's content ID. This is used when the disposition is set to `“inline”` and the attachment is an image, allowing the file to be displayed within the body of your email." } }, "required": [ @@ -177,15 +178,11 @@ }, "template_id": { "type": "string", - "description": "The id of a template that you would like to use. If you use a template that contains a subject and content (either text or html), you do not need to specify those at the personalizations nor message level. " - }, - "sections": { - "type": "object", - "description": "An object of key/value pairs that define block sections of code to be used as substitutions." + "description": "An email template ID. A template that contains a subject and content — either text or html — will override any subject and content values specified at the personalizations or message level." }, "headers": { - "type": "object", - "description": "An object containing key/value pairs of header names and the value to substitute for them. You must ensure these are properly encoded if they contain unicode characters. Must not be one of the reserved headers." + "description": "An object containing key/value pairs of header names and the value to substitute for them. The key/value pairs must be strings. You must ensure these are properly encoded if they contain unicode characters. These headers cannot be one of the reserved headers.", + "type": "object" }, "categories": { "type": "array", @@ -198,16 +195,16 @@ } }, "custom_args": { - "type": "object", - "description": "Values that are specific to the entire send that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by personalizations[x].custom_args if that parameter has been defined. Total custom args size may not exceed 10,000 bytes." + "description": "Values that are specific to the entire send that will be carried along with the email and its activity data. Key/value pairs must be strings. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by `custom_args` set at the personalizations level. Total `custom_args` size may not exceed 10,000 bytes.", + "type": "string" }, "send_at": { "type": "integer", - "description": "A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the personalizations[x].send_at parameter. Scheduling more ta 72 hours in advance is forbidden." + "description": "A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the `send_at` parameter set at the personalizations level. Delivery cannot be scheduled more than 72 hours in advance. If you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid peak times — for example, scheduling at 10:53 — can result in lower deferral rates due to the reduced traffic during off-peak times." }, "batch_id": { "type": "string", - "description": "This ID represents a batch of emails to be sent at the same time. Including a batch_id in your request allows you include this email in that batch, and also enables you to cancel or pause the delivery of that batch. For more information, see https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_schedule_send.html " + "description": "An ID representing a batch of emails to be sent at the same time. Including a `batch_id` in your request allows you include this email in that batch. It also enables you to cancel or pause the delivery of that batch. For more information, see the [Cancel Scheduled Sends API](https://sendgrid.com/docs/api-reference/)." }, "asm": { "type": "object", @@ -240,24 +237,19 @@ "type": "object", "description": "A collection of different mail settings that you can use to specify how you would like this email to be handled.", "properties": { - "bcc": { + "bypass_list_management": { "type": "object", - "description": "This allows you to have a blind carbon copy automatically sent to the specified email address for every email that is sent.", + "description": "Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email. This filter cannot be combined with any other bypass filters. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", "properties": { "enable": { "type": "boolean", "description": "Indicates if this setting is enabled." - }, - "email": { - "type": "string", - "description": "The email address that you would like to receive the BCC.", - "format": "email" } } }, - "bypass_list_management": { + "bypass_spam_management": { "type": "object", - "description": "Allows you to bypass all unsubscribe groups and suppressions to ensure that the email is delivered to every single recipient. This should only be used in emergencies when it is absolutely necessary that every recipient receives your email.", + "description": "Allows you to bypass the spam report list to ensure that the email is delivered to recipients. Bounce and unsubscribe lists will still be checked; addresses on these other lists will not receive the message. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", "properties": { "enable": { "type": "boolean", @@ -265,27 +257,19 @@ } } }, - "footer": { + "bypass_bounce_management": { "type": "object", - "description": "The default footer that you would like included on every email.", + "description": "Allows you to bypass the bounce list to ensure that the email is delivered to recipients. Spam report and unsubscribe lists will still be checked; addresses on these other lists will not receive the message. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", "properties": { "enable": { "type": "boolean", "description": "Indicates if this setting is enabled." - }, - "text": { - "type": "string", - "description": "The plain text content of your footer." - }, - "html": { - "type": "string", - "description": "The HTML content of your footer." } } }, - "sandbox_mode": { + "bypass_unsubscribe_management": { "type": "object", - "description": "This allows you to send a test email to ensure that your request body is valid and formatted correctly.", + "description": "Allows you to bypass the global unsubscribe list to ensure that the email is delivered to recipients. Bounce and spam report lists will still be checked; addresses on these other lists will not receive the message. This filter applies only to global unsubscribes and will not bypass group unsubscribes. This filter cannot be combined with the `bypass_list_management` filter. See our [documentation](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) for more about bypass filters.", "properties": { "enable": { "type": "boolean", @@ -293,23 +277,31 @@ } } }, - "spam_check": { + "footer": { "type": "object", - "description": "This allows you to test the content of your email for spam.", + "description": "The default footer that you would like included on every email.", "properties": { "enable": { "type": "boolean", "description": "Indicates if this setting is enabled." }, - "threshold": { - "type": "integer", - "description": "The threshold used to determine if your content qualifies as spam on a scale from 1 to 10, with 10 being most strict, or most likely to be considered as spam.", - "minimum": 1, - "maximum": 10 + "text": { + "type": "string", + "description": "The plain text content of your footer." }, - "post_to_url": { + "html": { "type": "string", - "description": "An Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to." + "description": "The HTML content of your footer." + } + } + }, + "sandbox_mode": { + "type": "object", + "description": "Sandbox Mode allows you to send a test email to ensure that your request body is valid and formatted correctly.", + "properties": { + "enable": { + "type": "boolean", + "description": "Indicates if this setting is enabled." } } } @@ -321,7 +313,7 @@ "properties": { "click_tracking": { "type": "object", - "description": "Allows you to track whether a recipient clicked a link in your email.", + "description": "Allows you to track if a recipient clicked a link in your email.", "properties": { "enable": { "type": "boolean", @@ -329,13 +321,13 @@ }, "enable_text": { "type": "boolean", - "description": "Indicates if this setting should be included in the text/plain portion of your email." + "description": "Indicates if this setting should be included in the `text/plain` portion of your email." } } }, "open_tracking": { "type": "object", - "description": "Allows you to track whether the email was opened or not, but including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened.", + "description": "Allows you to track if the email was opened by including a single pixel image in the body of the content. When the pixel is loaded, Twilio SendGrid can log that the email was opened.", "properties": { "enable": { "type": "boolean", @@ -349,7 +341,7 @@ }, "subscription_tracking": { "type": "object", - "description": "Allows you to insert a subscription management link at the bottom of the text and html bodies of your email. If you would like to specify the location of the link within your email, you may use the substitution_tag.", + "description": "Allows you to insert a subscription management link at the bottom of the text and HTML bodies of your email. If you would like to specify the location of the link within your email, you may use the `substitution_tag`.", "properties": { "enable": { "type": "boolean", @@ -357,15 +349,15 @@ }, "text": { "type": "string", - "description": "Text to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>" + "description": "Text to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>" }, "html": { "type": "string", - "description": "HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>" + "description": "HTML to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %>" }, "substitution_tag": { "type": "string", - "description": "A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting." + "description": "A tag that will be replaced with the unsubscribe URL. for example: `[unsubscribe_url]`. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location with no additional formatting." } } }, @@ -387,15 +379,15 @@ }, "utm_term": { "type": "string", - "description": "Used to identify any paid keywords.\t" + "description": "Used to identify any paid keywords." }, "utm_content": { "type": "string", - "description": "Used to differentiate your campaign from advertisements.\t" + "description": "Used to differentiate your campaign from advertisements." }, "utm_campaign": { "type": "string", - "description": "The name of the campaign.\t" + "description": "The name of the campaign." } } } @@ -413,56 +405,180 @@ { "to": [ { - "email": "john.doe@example.com", + "email": "john_doe@example.com", "name": "John Doe" + }, + { + "email": "julia_doe@example.com", + "name": "Julia Doe" + } + ], + "cc": [ + { + "email": "jane_doe@example.com", + "name": "Jane Doe" + } + ], + "bcc": [ + { + "email": "james_doe@example.com", + "name": "Jim Doe" + } + ] + }, + { + "from": { + "email": "sales@example.com", + "name": "Example Sales Team" + }, + "to": [ + { + "email": "janice_doe@example.com", + "name": "Janice Doe" } ], - "subject": "Hello, World!" + "bcc": [ + { + "email": "jordan_doe@example.com", + "name": "Jordan Doe" + } + ] } ], "from": { - "email": "sam.smith@example.com", - "name": "Sam Smith" + "email": "orders@example.com", + "name": "Example Order Confirmation" }, "reply_to": { - "email": "sam.smith@example.com", - "name": "Sam Smith" + "email": "customer_service@example.com", + "name": "Example Customer Service Team" }, - "subject": "Hello, World!", + "subject": "Your Example Order Confirmation", "content": [ { "type": "text/html", - "value": "

Hello, world!

" + "value": "

Hello from Twilio SendGrid!

Sending with the email service trusted by developers and marketers for time-savings, scalability, and delivery expertise.

%open-track%

" } - ] + ], + "attachments": [ + { + "content": "PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg==", + "filename": "index.html", + "type": "text/html", + "disposition": "attachment" + } + ], + "categories": [ + "cake", + "pie", + "baking" + ], + "send_at": 1617260400, + "batch_id": "AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl", + "asm": { + "group_id": 12345, + "groups_to_display": [ + 12345 + ] + }, + "ip_pool_name": "transactional email", + "mail_settings": { + "bypass_list_management": { + "enable": false + }, + "footer": { + "enable": false + }, + "sandbox_mode": { + "enable": false + } + }, + "tracking_settings": { + "click_tracking": { + "enable": true, + "enable_text": false + }, + "open_tracking": { + "enable": true, + "substitution_tag": "%open-track%" + }, + "subscription_tracking": { + "enable": false + } + } } } } ], "responses": { "202": { - "description": "", - "schema": { - "type": "null" - } + "description": "" }, "400": { - "description": "", - "schema": { - "$ref": "#/definitions/errors" - } + "$ref": "#/responses/trait:mailSendErrors:400" }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/errors" - } + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" }, "413": { + "$ref": "#/responses/trait:mailSendErrors:413" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/mail/batch": { + "post": { + "operationId": "POST_mail-batch", + "summary": "Create a batch ID", + "tags": [ + "Cancel Scheduled Sends" + ], + "description": "**This endpoint allows you to generate a new batch ID.**\n\nOnce a `batch_id` is created, you can associate it with a scheduled send using the `/mail/send` endpoint. Passing the `batch_id` as a field in the `/mail/send` request body will assign the ID to the send you are creating.\n\nOnce an ID is associated with a scheduled send, the send can be accessed and its send status can be modified using the `batch_id`.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/errors" + "$ref": "#/definitions/mail_batch_id" + }, + "examples": { + "application/json": { + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" + } } + }, + "400": { + "$ref": "#/responses/trait:cancelScheduledSendsErrors:400" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -472,140 +588,72 @@ ] } }, - "/alerts": { + "/user/scheduled_sends": { "post": { - "operationId": "POST_alerts", - "summary": "Create a new Alert", + "operationId": "POST_user-scheduled_sends", + "summary": "Cancel or pause a scheduled send", "tags": [ - "Alerts" - ], - "description": "**This endpoint allows you to create a new alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint:\n\n* `usage_limit` allows you to set the threshold at which an alert will be sent.\n* `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Cancel Scheduled Sends" ], + "description": "**This endpoint allows you to cancel or pause a scheduled send associated with a `batch_id`.**\n\nPassing this endpoint a `batch_id` and status will cancel or pause the scheduled send.\n\nOnce a scheduled send is set to `pause` or `cancel` you must use the \"Update a scheduled send\" endpoint to change its status or the \"Delete a cancellation or pause from a scheduled send\" endpoint to remove the status. Passing a status change to a scheduled send that has already been paused or cancelled will result in a `400` level status code.\n\nIf the maximum number of cancellations/pauses are added to a send, a `400` level status code will be returned.", "parameters": [ { "name": "body", "in": "body", "schema": { + "title": "Cancel or pause a scheduled send request", "type": "object", "properties": { - "type": { + "batch_id": { "type": "string", - "description": "The type of alert you want to create. Can be either usage_limit or stats_notification.\nExample: usage_limit", - "enum": [ - "stats_notification", - "usage_limit" - ] - }, - "email_to": { - "type": [ - "string", - "null" - ], - "description": "The email address the alert will be sent to.\nExample: test@example.com" + "description": "The batch ID is the identifier that your scheduled mail sends share.", + "pattern": "^[a-zA-Z0-9]" }, - "frequency": { + "status": { "type": "string", - "description": "Required for stats_notification. How frequently the alert will be sent.\nExample: daily" - }, - "percentage": { - "type": "integer", - "description": "Required for usage_alert. When this usage threshold is reached, the alert will be sent.\nExample: 90" + "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": [ - "type", - "email_to" + "batch_id", + "status" ], "example": { - "type": "stats_notification", - "email_to": "example@example.com", - "frequency": "daily" + "batch_id": "YOUR_BATCH_ID", + "status": "pause" } } }, { - "name": "Authorization", - "in": "header", - "type": "string" - }, - { - "name": "on-behalf-of", - "in": "header", - "type": "string" + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to." - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "type": { - "type": "string", - "description": "The type of alert." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "percentage": { - "type": "integer", - "description": "\"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - } - }, - "required": [ - "created_at", - "email_to", - "id", - "type", - "updated_at" - ] - }, - "examples": { - "application/json": { - "created_at": 1451520930, - "email_to": "test@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451520930 - } + "$ref": "#/definitions/user_scheduled_send_status" } }, "400": { - "description": "", - "schema": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string" - } - } - } + "$ref": "#/responses/trait:cancelScheduledSendsErrors:400" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -615,28 +663,13 @@ ] }, "get": { - "operationId": "GET_alerts", - "summary": "Retrieve all alerts", + "operationId": "GET_user-scheduled_sends", + "summary": "Retrieve all scheduled sends", "tags": [ - "Alerts" - ], - "description": "**This endpoint allows you to retieve all of your alerts.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", - "produces": [ - "application/json" + "Cancel Scheduled Sends" ], + "description": "**This endpoint allows you to retrieve all cancelled and paused scheduled send information.**\n\nThis endpoint will return only the scheduled sends that are associated with a `batch_id`. If you have scheduled a send using the `/mail/send` endpoint and the `send_at` field but no `batch_id`, the send will be scheduled for delivery; however, it will not be returned by this endpoint. For this reason, you should assign a `batch_id` to any scheduled send you may need to pause or cancel in the future.", "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "name": "Authorization", - "in": "header", - "type": "string" - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -646,79 +679,37 @@ "description": "", "schema": { "type": "array", - "description": "The list of alerts.", "items": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "percentage": { - "type": "integer", - "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - }, - "type": { - "type": "string", - "description": "The type of alert.", - "enum": [ - "usage_limit", - "stats_notification" - ] - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." - } - }, - "required": [ - "created_at", - "email_to", - "id", - "type" - ] + "$ref": "#/definitions/user_scheduled_send_status" } }, "examples": { "application/json": [ { - "created_at": 1451498784, - "email_to": "example1@example.com", - "id": 46, - "percentage": 90, - "type": "usage_limit", - "updated_at": 1451498784 - }, - { - "created_at": 1451498812, - "email_to": "example2@example.com", - "frequency": "monthly", - "id": 47, - "type": "stats_notification", - "updated_at": 1451498812 + "batch_id": "QzZmYzLTVWIwYgYzJlM2NhNWI", + "status": "cancel" }, { - "created_at": 1451520930, - "email_to": "example3@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451520930 + "batch_id": "mQzZmYzLTVlM2NhNWIwYgYzJl", + "status": "cancel" } ] } + }, + "400": { + "$ref": "#/responses/trait:cancelScheduledSendsErrors:400" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -728,32 +719,23 @@ ] } }, - "/alerts/{alert_id}": { + "/mail/batch/{batch_id}": { "parameters": [ { - "name": "alert_id", + "name": "batch_id", "in": "path", - "description": "The ID of the alert you would like to retrieve.", "required": true, - "type": "integer" + "type": "string" } ], "get": { - "operationId": "GET_alerts-alert_id", - "summary": "Retrieve a specific alert", + "operationId": "GET_mail-batch-batch_id", + "summary": "Validate batch ID", "tags": [ - "Alerts" - ], - "description": "**This endpoint allows you to retrieve a specific alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", - "produces": [ - "application/json" + "Cancel Scheduled Sends" ], + "description": "**This endpoint allows you to validate a batch ID.**\n\nWhen you pass a valid `batch_id` to this endpoint, it will return a `200` status code and the batch ID itself.\n\nIf you pass an invalid `batch_id` to the endpoint, you will receive a `400` level status code and an error message.\n\nA `batch_id` does not need to be assigned to a scheduled send to be considered valid. A successful response means only that the `batch_id` has been created, but it does not indicate that it has been associated with a send.", "parameters": [ - { - "name": "Authorization", - "in": "header", - "type": "string" - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -762,59 +744,28 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to." - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "type": { - "type": "string", - "description": "The type of alert.", - "enum": [ - "usage_alert", - "stats_notification" - ] - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "percentage": { - "type": "integer", - "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - } - }, - "required": [ - "created_at", - "email_to", - "id", - "type", - "updated_at" - ] + "$ref": "#/definitions/mail_batch_id" }, "examples": { "application/json": { - "created_at": 1451520930, - "email_to": "example@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451520930 + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" } } + }, + "400": { + "$ref": "#/responses/trait:cancelScheduledSendsErrors:400" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -822,26 +773,66 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_alerts-alert_id", - "summary": "Delete an alert", + } + }, + "/user/scheduled_sends/{batch_id}": { + "parameters": [ + { + "name": "batch_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_user-scheduled_sends-batch_id", + "summary": "Retrieve scheduled send", "tags": [ - "Alerts" + "Cancel Scheduled Sends" ], - "description": "**This endpoint allows you to delete an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", + "description": "**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "object", - "properties": {} + "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" + } + ] } + }, + "400": { + "$ref": "#/responses/trait:cancelScheduledSendsErrors:400" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -851,18 +842,12 @@ ] }, "patch": { - "operationId": "PATCH_alerts-alert_id", - "summary": "Update an alert", + "operationId": "PATCH_user-scheduled_sends-batch_id", + "summary": "Update a scheduled send", "tags": [ - "Alerts" - ], - "description": "**This endpoint allows you to update an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Cancel Scheduled Sends" ], + "description": "**This endpoint allows you to update the status of a scheduled send for the given `batch_id`.**\n\nIf you have already set a `cancel` or `pause` status on a scheduled send using the \"Cancel or pause a scheduled send\" endpoint, you can update it's status using this endpoint. Attempting to update a status once it has been set with the \"Cancel or pause a scheduled send\" endpoint will result in a `400` error.", "parameters": [ { "name": "body", @@ -870,21 +855,20 @@ "schema": { "type": "object", "properties": { - "email_to": { - "type": "string", - "description": "The new email address you want your alert to be sent to.\nExample: test@example.com" - }, - "frequency": { + "status": { "type": "string", - "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly" - }, - "percentage": { - "type": "integer", - "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90" + "description": "The status you would like the scheduled send to have.", + "enum": [ + "cancel", + "pause" + ] } }, + "required": [ + "status" + ], "example": { - "email_to": "example@example.com" + "status": "pause" } } }, @@ -893,62 +877,26 @@ } ], "responses": { - "200": { + "204": { "description": "", "schema": { - "type": "object", - "properties": { - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was created." - }, - "email_to": { - "type": "string", - "description": "The email address that the alert will be sent to." - }, - "frequency": { - "type": "string", - "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." - }, - "id": { - "type": "integer", - "description": "The ID of the alert." - }, - "type": { - "type": "string", - "description": "The type of alert.", - "enum": [ - "usage_alert", - "stats_notification" - ] - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the alert was last modified." - }, - "percentage": { - "type": "integer", - "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." - } - }, - "required": [ - "created_at", - "email_to", - "id", - "type", - "updated_at" - ] - }, - "examples": { - "application/json": { - "created_at": 1451520930, - "email_to": "example@example.com", - "frequency": "daily", - "id": 48, - "type": "stats_notification", - "updated_at": 1451522691 - } + "type": "null" } + }, + "400": { + "$ref": "#/responses/trait:cancelScheduledSendsErrors:400" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -956,73 +904,37 @@ "Authorization": [] } ] - } - }, - "/api_keys": { - "get": { - "operationId": "GET_api_keys", - "summary": "Retrieve all API Keys belonging to the authenticated user", + }, + "delete": { + "operationId": "DELETE_user-scheduled_sends-batch_id", + "summary": "Delete a cancellation or pause from a scheduled send", "tags": [ - "API Keys" - ], - "description": "**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).", - "produces": [ - "application/json" + "Cancel Scheduled Sends" ], + "description": "**This endpoint allows you to delete the cancellation/pause of a scheduled send.**\n\nScheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", "parameters": [ - { - "name": "limit", - "in": "query", - "type": "integer" - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/definitions/api_key_name_id" - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "name": "API Key Name", - "api_key_id": "some-apikey-id" - }, - { - "name": "API Key Name 2", - "api_key_id": "another-apikey-id" - } - ] - } - } + "204": { + "description": "" + }, + "400": { + "$ref": "#/responses/trait:cancelScheduledSendsErrors:400" }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1030,20 +942,16 @@ "Authorization": [] } ] - }, + } + }, + "/api_keys": { "post": { "operationId": "create-api-keys", "summary": "Create API keys", "tags": [ "API Keys" ], - "description": "**This endpoint allows you to create a new random API Key for the user.**\n\nA JSON request body containing a \"name\" property is required. If number of maximum keys is reached, HTTP 403 will be returned.\n\nThere is a limit of 100 API Keys on your account.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\nSee the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "description": "**This endpoint allows you to create a new API Key for the user.**\n\nTo create your initial SendGrid API Key, you should [use the SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management.\n\n> There is a limit of 100 API Keys on your account.\n\nA JSON request body containing a `name` property is required when making requests to this endpoint. If the number of maximum keys, 100, is reached, a `403` status will be returned.\n\nThough the `name` field is required, it does not need to be unique. A unique API key ID will be generated for each key you create and returned in the response body.\n\nIt is not necessary to pass a `scopes` field to the API when creating a key, but you should be aware that omitting the `scopes` field from your request will create a key with \"Full Access\" permissions by default.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.", "parameters": [ { "name": "body", @@ -1061,9 +969,6 @@ "items": { "type": "string" } - }, - "sample": { - "type": "string" } }, "required": [ @@ -1075,8 +980,7 @@ "mail.send", "alerts.create", "alerts.read" - ], - "sample": "data" + ] } } }, @@ -1121,52 +1025,84 @@ } }, "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "name", - "message": "missing required argument" - } - ] - } - } + "$ref": "#/responses/trait:apiKeysErrors:400" }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:globalErrors:401" }, "403": { + "$ref": "#/responses/trait:apiKeysErrors:403" + }, + "404": { + "$ref": "#/responses/trait:apiKeysErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_api_keys", + "summary": "Retrieve all API Keys belonging to the authenticated user", + "tags": [ + "API Keys" + ], + "description": "**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nA successful response from this API will include all available API keys' names and IDs.\n\nFor security reasons, there is not a way to retrieve the key itself after it's created. If you lose your API key, you must create a new one. Only the \"Create API keys\" endpoint will return a key to you and only at the time of creation.\n\nAn `api_key_id` can be used to update or delete the key, as well as retrieve the key's details, such as its scopes.", + "parameters": [ + { + "name": "limit", + "in": "query", + "type": "integer" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/api_key_name_id" + } + } + } }, "examples": { "application/json": { - "errors": [ + "result": [ { - "field": null, - "message": "Cannot create more than 100 API Keys" + "name": "API Key Name", + "api_key_id": "some-apikey-id" + }, + { + "name": "API Key Name 2", + "api_key_id": "another-apikey-id" } ] } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1181,7 +1117,7 @@ { "name": "api_key_id", "in": "path", - "description": "The ID of the API Key for which you are requesting information.", + "description": "", "required": true, "type": "string" } @@ -1192,10 +1128,7 @@ "tags": [ "API Keys" ], - "description": "**This endpoint allows you to retrieve a single api key.**\n\nIf the API Key ID does not exist an HTTP 404 will be returned.", - "produces": [ - "application/json" - ], + "description": "**This endpoint allows you to retrieve a single API key using an `api_key_id`.**\n\nThe endpoint will return a key's name, ID, and scopes. If the API Key ID does not, exist a `404` status will be returned.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -1230,85 +1163,20 @@ } } }, + "400": { + "$ref": "#/responses/trait:apiKeysErrors:400" + }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:globalErrors:401" }, - "404": { - "description": "Unexpected error in API call. See HTTP response body for details.", - "schema": { - "type": "object" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "unable to find API Key" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "operationId": "DELETE_api_keys-api_key_id", - "summary": "Delete API keys", - "tags": [ - "API Keys" - ], - "description": "**This endpoint allows you to revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are deleting.|", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - }, - "examples": { - "application/json": null - } + "403": { + "$ref": "#/responses/trait:apiKeysErrors:403" }, "404": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "unable to find API Key" - } - ] - } - } + "$ref": "#/responses/trait:apiKeysErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1319,17 +1187,11 @@ }, "patch": { "operationId": "PATCH_api_keys-api_key_id", - "summary": "Update API keys", + "summary": "Update API key name", "tags": [ "API Keys" ], - "description": "**This endpoint allows you to update the name of an existing API Key.**\n\nA JSON request body with a \"name\" property is required.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are updating.|", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "description": "**This endpoint allows you to update the name of an existing API Key.**\n\nYou must pass this endpoint a JSON request body with a `name` property, which will be used to rename the key associated with the `api_key_id` passed in the URL.", "parameters": [ { "name": "body", @@ -1342,6 +1204,9 @@ "description": "The new name of the API Key." } }, + "required": [ + "name" + ], "example": { "name": "A New Hope" } @@ -1364,21 +1229,20 @@ } } }, + "400": { + "$ref": "#/responses/trait:apiKeysErrors:400" + }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1389,17 +1253,11 @@ }, "put": { "operationId": "PUT_api_keys-api_key_id", - "summary": "Update the name & scopes of an API Key", + "summary": "Update API key name and scopes", "tags": [ "API Keys" ], - "description": "**This endpoint allows you to update the name and scopes of a given API key.**\n\nA JSON request body with a \"name\" property is required.\nMost provide the list of all the scopes an api key should have.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], + "description": "**This endpoint allows you to update the name and scopes of a given API key.**\n\nYou must pass this endpoint a JSON request body with a `name` field and a `scopes` array containing at least one scope. The `name` and `scopes` fields will be used to update the key associated with the `api_key_id` in the request URL.\n\nIf you need to update a key's scopes only, pass the `name` field with the key's existing name; the `name` will not be modified. If you need to update a key's name only, use the \"Update API key name\" endpoint.\n\nSee the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes.", "parameters": [ { "name": "body", @@ -1417,8 +1275,11 @@ } } }, + "required": [ + "name" + ], "example": { - "name": "A New Hope", + "name": "Profiles key", "scopes": [ "user.profile.read", "user.profile.update" @@ -1439,7 +1300,7 @@ "examples": { "application/json": { "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope", + "name": "Profiles Key", "scopes": [ "user.profile.read", "user.profile.update" @@ -1448,42 +1309,19 @@ } }, "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" - } - ] - } - } + "$ref": "#/responses/trait:apiKeysErrors:400" }, "401": { - "description": "", - "schema": { - "type": "object" - } + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" }, "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" - } - ] - } - } + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1491,91 +1329,37 @@ "Authorization": [] } ] - } - }, - "/suppression/blocks": { - "get": { - "operationId": "GET_suppression-blocks", - "summary": "Retrieve all blocks", + }, + "delete": { + "operationId": "DELETE_api_keys-api_key_id", + "summary": "Delete API keys", "tags": [ - "Blocks API" - ], - "description": "**This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.**\n\nThere are several causes for [blocked](https://sendgrid.com/docs/Glossary/blocks.html) emails: for example, your mail server IP address is on an ISP blacklist, or blocked by an ISP, or if the receiving server flags the message content.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", - "produces": [ - "application/json" + "API Keys" ], + "description": "**This endpoint allows you to revoke an existing API Key using an `api_key_id`**\n\nAuthentications using a revoked API Key will fail after after some small propogation delay. If the API Key ID does not exist, a `404` status will be returned.", "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when a blocked email was created (inclusive).", - "type": "integer" - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when a blocked email was created (inclusive).", - "type": "integer" - }, - { - "name": "limit", - "in": "query", - "description": "Limit the number of results to be displayed per page.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list to begin displaying results.", - "type": "integer" - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the email address was added to the blocks list." - }, - "email": { - "type": "string", - "description": "The email address that was added to the block list." - }, - "reason": { - "type": "string", - "description": "An explanation for the reason of the block." - }, - "status": { - "type": "string", - "description": "The status of the block." - } - }, - "required": [ - "created", - "email", - "reason", - "status" - ] - } - }, - "examples": { - "application/json": [ - { - "created": 1443651154, - "email": "example@example.com", - "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", - "status": "4.0.0" - } - ] - } + "204": { + "description": "" + }, + "400": { + "$ref": "#/responses/trait:apiKeysErrors:400" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1583,199 +1367,31 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_suppression-blocks", - "summary": "Delete blocks", + } + }, + "/scopes": { + "get": { + "operationId": "GET_scopes", + "summary": "Retrieve a list of scopes for which this user has access.", "tags": [ - "Blocks API" - ], - "description": "**This endpoint allows you to delete all email addresses on your blocks list.**\n\nThere are two options for deleting blocked emails: \n\n1. You can delete all blocked emails by setting `delete_all` to true in the request body. \n2. You can delete some blocked emails by specifying the email addresses in an array in the request body.\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", - "produces": [ - "application/json" + "API Key Permissions" ], + "description": "**This endpoint returns a list of all scopes that this user has access to.**\n\nAPI Keys are used to authenticate with [SendGrid's v3 API](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization).\n\nAPI Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access.\n\nThis endpoint returns all the scopes assigned to the key you use to authenticate with it. To retrieve the scopes assigned to another key, you can pass an API key ID to the \"Retrieve an existing API key\" endpoint.\n\nFor a more detailed explanation of how you can use API Key permissions, please visit our [API Keys documentation](https://sendgrid.com/docs/ui/account-and-settings/api-keys/).", "parameters": [ { - "name": "body", - "in": "body", + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", "schema": { "type": "object", "properties": { - "delete_all": { - "type": "boolean", - "description": "Indicates if you want to delete all blocked email addresses." - }, - "emails": { + "scopes": { "type": "array", - "description": "The specific blocked email addresses that you want to delete.", - "items": { - "type": "string" - } - } - }, - "example": { - "delete_all": false, - "emails": [ - "example1@example.com", - "example2@example.com" - ] - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/suppression/blocks/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address of the specific block.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_suppression-blocks-email", - "summary": "Retrieve a specific block", - "tags": [ - "Blocks API" - ], - "description": "**This endpoint allows you to retrieve a specific email address from your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the block was created." - }, - "email": { - "type": "string", - "description": "The email address of the recipient that was blocked." - }, - "reason": { - "type": "string", - "description": "The reason why the email was blocked." - }, - "status": { - "type": "string", - "description": "The status of the block." - } - }, - "required": [ - "created", - "email", - "reason" - ] - } - }, - "examples": { - "application/json": [ - { - "created": 1443651154, - "email": "example@example.com", - "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", - "status": "4.0.0" - } - ] - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "operationId": "DELETE_suppression-blocks-email", - "summary": "Delete a specific block", - "tags": [ - "Blocks API" - ], - "description": "**This endpoint allows you to delete a specific email address from your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - } - } - }, - "/scopes": { - "get": { - "operationId": "GET_scopes", - "summary": "Retrieve a list of scopes for which this user has access.", - "tags": [ - "API Key Permissions" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The list of scopes for which this user has access.", - "uniqueItems": true, + "description": "The list of scopes for which this user has access.", + "uniqueItems": true, "items": { "type": "string" } @@ -1835,6 +1451,15 @@ ] } } + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1844,37 +1469,15 @@ ] } }, - "/suppression/bounces": { + "/user/settings/enforced_tls": { "get": { - "operationId": "GET_suppression-bounces", - "summary": "Retrieve all bounces", + "operationId": "GET_user-settings-enforced_tls", + "summary": "Retrieve current Enforced TLS settings.", "tags": [ - "Bounces API" - ], - "description": "**This endpoint allows you to retrieve all of your bounces.**\n\nA bounced email is when the message is undeliverable and then 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)", - "produces": [ - "application/json" + "Settings - Enforced TLS" ], + "description": "**This endpoint allows you to retrieve your current Enforced TLS settings.**\n\nThe Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate.\n\nIf either `require_tls` or `require_valid_cert` is set to `true`, the recipient must support TLS 1.1 or higher or have a valid certificate. If these conditions are not met, Twilio SendGrid will drop the message and send a block event with “TLS required but not supported” as the description.", "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", - "type": "integer" - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when a bounce was created (inclusive).", - "type": "integer" - }, - { - "name": "Accept", - "in": "header", - "required": true, - "type": "string", - "default": "application/json" - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -1883,57 +1486,26 @@ "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" + "$ref": "#/definitions/enforced-tls-request-response" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "require_tls": false, + "require_valid_cert": false } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -1942,43 +1514,108 @@ } ] }, - "delete": { - "operationId": "DELETE_suppression-bounces", - "summary": "Delete bounces", + "patch": { + "operationId": "PATCH_user-settings-enforced_tls", + "summary": "Update Enforced TLS settings", "tags": [ - "Bounces API" - ], - "description": "**This endpoint allows you to delete all of your bounces. You can also use this endpoint to remove a specific email address from your bounce list.**\n\nA bounced email is when the message is undeliverable and then returned to the server that sent it.\n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)\n\nNote: the `delete_all` and `emails` parameters should be used independently of each other as they have different purposes.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Settings - Enforced TLS" ], + "description": "**This endpoint allows you to update your Enforced TLS settings.**\n\nTo require TLS from recipients, set `require_tls` to `true`. If either `require_tls` or `require_valid_cert` is set to `true`, the recipient must support TLS 1.1 or higher or have a valid certificate. If these conditions are not met, Twilio SendGrid will drop the message and send a block event with “TLS required but not supported” as the description.\n\n> Twilio SendGrid supports TLS 1.1 and higher and does not support older versions of TLS due to security vulnerabilities.", "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": { + "$ref": "#/definitions/enforced-tls-request-response", + "example": { + "require_tls": true, + "require_valid_cert": false + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/enforced-tls-request-response" + }, + "examples": { + "application/json": { + "require_tls": true, + "require_valid_cert": false + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/access_settings/whitelist": { + "post": { + "operationId": "POST_access_settings-whitelist", + "summary": "Add one or more IPs to the allow list", + "tags": [ + "IP Access Management" + ], + "description": "**This endpoint allows you to add one or more allowed IP addresses.**\n\nTo allow one or more IP addresses, pass them to this endpoint in an array. Once an IP address is added to your allow list, it will be assigned an `id` that can be used to remove the address. You can retrieve the ID associated with an IP using the \"#endpoint:nzCz472S9yaNpgmDu\" endpoint.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "ips": { "type": "array", - "description": "Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter.", + "description": "An array containing the IP(s) you want to allow.", "items": { - "type": "string" + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "An IP address that you want to allow." + } + }, + "required": [ + "ip" + ] } } }, + "required": [ + "ips" + ], "example": { - "delete_all": true, - "emails": [ - "example@example.com", - "example2@example.com" + "ips": [ + { + "ip": "192.168.1.1" + }, + { + "ip": "192.*.*.*" + }, + { + "ip": "192.168.1.3/32" + } ] } } @@ -1988,27 +1625,47 @@ } ], "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "401": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/ip-access-response" }, "examples": { "application/json": { - "errors": [ + "result": [ { - "field": null, - "message": "authorization required" + "id": 1, + "ip": "192.168.1.1/32", + "created_at": 1441824715, + "updated_at": 1441824715 + }, + { + "id": 2, + "ip": "192.0.0.0/8", + "created_at": 1441824715, + "updated_at": 1441824715 + }, + { + "id": 3, + "ip": "192.168.1.3/32", + "created_at": 1441824715, + "updated_at": 1441824715 } ] } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -2016,27 +1673,14 @@ "Authorization": [] } ] - } - }, - "/suppression/bounces/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "required": true, - "type": "string" - } - ], + }, "get": { - "operationId": "GET_suppression-bounces-email", - "summary": "Retrieve a Bounce", + "operationId": "GET_access_settings-whitelist", + "summary": "Retrieve a list of currently allowed IPs", "tags": [ - "Bounces API" - ], - "description": "**This endpoint allows you to retrieve a specific bounce for a given email address.**\n\nA bounced email is when the message is undeliverable and then returned to the server that sent it.\n\nFor more information see: \n\n* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information\n* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html)\n* [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html)", - "produces": [ - "application/json" + "IP Access Management" ], + "description": "**This endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account.**\n\nEach IP address returned to you will have `created_at` and `updated_at` dates. Each IP will also be associated with an `id` that can be used to remove the address from your allow list.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -2046,35 +1690,44 @@ "200": { "description": "", "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer" - }, - "email": { - "type": "string" + "$ref": "#/definitions/ip-access-response" + }, + "examples": { + "application/json": { + "result": [ + { + "id": 1, + "ip": "192.168.1.1/32", + "created_at": 1441824715, + "updated_at": 1441824715 }, - "reason": { - "type": "string" + { + "id": 2, + "ip": "192.168.1.2/32", + "created_at": 1441824715, + "updated_at": 1441824715 }, - "status": { - "type": "string" + { + "id": 3, + "ip": "192.168.1.3/32", + "created_at": 1441824715, + "updated_at": 1441824715 } - } + ] } - }, - "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" - } - ] } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -2084,29 +1737,34 @@ ] }, "delete": { - "operationId": "DELETE_suppression-bounces-email", - "summary": "Delete a bounce", + "operationId": "DELETE_access_settings-whitelist", + "summary": "Remove one or more IPs from the allow list", "tags": [ - "Bounces API" - ], - "description": "**This endpoint allows you to remove an email address from your bounce list.**\n\nA bounced email is when the message is undeliverable and then 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)", - "produces": [ - "application/json" + "IP Access Management" ], + "description": "**This endpoint allows you to remove one or more IP addresses from your list of allowed addresses.**\n\nTo remove one or more IP addresses, pass this endpoint an array containing the ID(s) associated with the IP(s) you intend to remove. You can retrieve the IDs associated with your allowed IP addresses using the \"#endpoint:nzCz472S9yaNpgmDu\" endpoint.\n\nIt is possible to remove your own IP address, which will block access to your account. You will need to submit a [support ticket](https://sendgrid.com/docs/ui/account-and-settings/support/) if this happens. For this reason, it is important to double check that you are removing only the IPs you intend to remove when using this endpoint.", "parameters": [ - { - "name": "email_address", - "in": "query", - "description": "The email address you would like to remove from the bounce list.", - "required": true, - "type": "string", - "format": "email" - }, { "name": "body", "in": "body", "schema": { - "type": "null" + "type": "object", + "properties": { + "ids": { + "type": "array", + "description": "An array of the IDs of the IP address that you want to remove from your allow list.", + "items": { + "type": "integer" + } + } + }, + "example": { + "ids": [ + 1, + 2, + 3 + ] + } } }, { @@ -2117,24 +1775,21 @@ "204": { "description": "", "schema": { - "type": "object" + "type": "object", + "properties": {} } }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -2144,185 +1799,24 @@ ] } }, - "/campaigns": { - "post": { - "operationId": "POST_campaigns", - "summary": "Create a Campaign", + "/access_settings/activity": { + "get": { + "operationId": "GET_access_settings-activity", + "summary": "Retrieve all recent access attempts", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to create a campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/campaign_request", - "example": { - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "

Check out our spring line!

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

Check out our spring line!

", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - } - }, - "400": { - "description": "\"title\": \"title can't be blank\"\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" - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "operationId": "GET_campaigns", - "summary": "Retrieve all Campaigns", - "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to retrieve a list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "produces": [ - "application/json" + "IP Access Management" ], + "description": "**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**", "parameters": [ { "name": "limit", "in": "query", - "description": "The number of results you would like to receive at a time.", + "description": "Limits the number of IPs to return.", "type": "integer", - "default": 10 + "default": 20 }, { - "name": "offset", - "in": "query", - "description": "The index of the first campaign to return, where 0 is the first campaign.", - "type": "integer", - "default": 0 + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { @@ -2333,89 +1827,84 @@ "properties": { "result": { "type": "array", + "description": "An array containing the IPs that recently attempted to access your account.", "items": { "type": "object", "properties": { - "categories": { - "type": "array", - "items": { - "type": "string" - } - }, - "custom_unsubscribe_url": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "id": { - "type": "integer" - }, - "ip_pool": { - "type": "string" - }, - "list_ids": { - "type": "array", - "items": { - "type": "integer" - } - }, - "plain_content": { - "type": "string" - }, - "segment_ids": { - "type": "array", - "items": { - "type": "integer" - } + "allowed": { + "type": "boolean", + "description": "Indicates if the IP address was granted access to the account." }, - "sender_id": { - "type": "integer" + "auth_method": { + "type": "string", + "description": "The authentication method used when attempting access." }, - "status": { - "type": "string" + "first_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the first access attempt was made." }, - "subject": { - "type": "string" + "ip": { + "type": "string", + "description": "The IP addressed used during the access attempt." }, - "suppression_group_id": { - "type": "integer" + "last_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the most recent access attempt was made" }, - "title": { - "type": "string" + "location": { + "type": "string", + "description": "The geographic location from which the access attempt originated." } - } + }, + "required": [ + "allowed", + "auth_method", + "first_at", + "ip", + "last_at", + "location" + ] } } - } + }, + "required": [ + "result" + ] }, "examples": { "application/json": { "result": [ { - "categories": [ - "spring line" - ], - "custom_unsubscribe_url": "", - "html_content": "

Check out our spring line!

", - "id": 986724, - "ip_pool": "marketing", - "list_ids": [ - 110 - ], - "plain_content": "Check out our spring line!", - "segment_ids": [ - 110 - ], - "sender_id": 124451, - "status": "Draft", - "subject": "New Products for Spring!", - "suppression_group_id": 42, - "title": "March Newsletter" + "allowed": false, + "auth_method": "Web", + "first_at": 1444087966, + "ip": "1.1.1.1", + "last_at": 1444406672, + "location": "Australia" + }, + { + "allowed": false, + "auth_method": "Web", + "first_at": 1444087505, + "ip": "1.2.3.48", + "last_at": 1444087505, + "location": "Mukilteo, Washington" } ] } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -2425,135 +1914,40 @@ ] } }, - "/campaigns/{campaign_id}": { + "/access_settings/whitelist/{rule_id}": { "parameters": [ { - "name": "campaign_id", + "name": "rule_id", "in": "path", - "description": "The id of the campaign you would like to retrieve.", + "description": "The ID of the allowed IP address that you want to retrieve.", "required": true, - "type": "integer" + "type": "string" } ], "get": { - "operationId": "GET_campaigns-campaign_id", - "summary": "Retrieve a single campaign", + "operationId": "GET_access_settings-whitelist-rule_id", + "summary": "Retrieve a specific allowed IP", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to retrieve a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "produces": [ - "application/json" + "IP Access Management" + ], + "description": "**This endpoint allows you to retreive a specific IP address that has been allowed to access your account.**\n\nYou must include the ID for the specific IP address you want to retrieve in your call. You can retrieve the IDs associated with your allowed IP addresses using the \"#endpoint:nzCz472S9yaNpgmDu\" endpoint.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "categories": { - "type": "array", - "items": { - "type": "string" - } - }, - "custom_unsubscribe_url": { - "type": "string" - }, - "html_content": { - "type": "string" - }, - "id": { - "type": "integer" - }, - "ip_pool": { - "type": "string" - }, - "list_ids": { - "type": "array", - "items": { - "type": "integer" - } - }, - "plain_content": { - "type": "string" - }, - "segment_ids": { - "type": "array", - "items": { - "type": "integer" - } - }, - "sender_id": { - "type": "integer" - }, - "status": { - "type": "string" - }, - "subject": { - "type": "string" - }, - "suppression_group_id": { - "type": "integer" - }, - "title": { - "type": "string" - } - } - }, - "examples": { - "application/json": { - "categories": [ - "spring line" - ], - "custom_unsubscribe_url": "", - "html_content": "

Check out our spring line!

", - "id": 986724, - "ip_pool": "marketing", - "list_ids": [ - 110 - ], - "plain_content": "Check out our spring line!", - "segment_ids": [ - 110 - ], - "sender_id": 124451, - "status": "Draft", - "subject": "New Products for Spring!", - "suppression_group_id": 42, - "title": "March Newsletter" - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "type": "object" + "$ref": "#/definitions/ip-access-response" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] + "id": 1, + "ip": "192.168.1.1", + "created_at": 1441824715, + "updated_at": 1441824715 } } } @@ -2565,51 +1959,23 @@ ] }, "delete": { - "operationId": "DELETE_campaigns-campaign_id", - "summary": "Delete a Campaign", + "operationId": "DELETE_access_settings-whitelist-rule_id", + "summary": "Remove a specific IP from the allowed list", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to delete a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "produces": [ - "application/json" + "IP Access Management" ], + "description": "**This endpoint allows you to remove a specific IP address from your list of allowed addresses.**\n\nWhen removing a specific IP address from your list, you must include the ID in your call. You can retrieve the IDs associated with your allowed IP addresses using the \"#endpoint:nzCz472S9yaNpgmDu\" endpoint.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { - "type": "null" - } - }, - "401": { - "description": "", - "schema": { - "type": "object" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "type": "object" + "type": "object", + "properties": {} } } }, @@ -2618,67 +1984,45 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_campaigns-campaign_id", - "summary": "Update a Campaign", + } + }, + "/sso/certificates": { + "post": { + "operationId": "POST_sso-certificates", + "summary": "Create an SSO Certificate", "tags": [ - "Campaigns API" - ], - "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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Certificates" ], + "description": "**This endpoint allows you to create an SSO certificate.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "title": "Update a Campaign request", "type": "object", + "description": "", "properties": { - "title": { - "type": "string", - "description": "The title of the campaign." - }, - "subject": { + "public_certificate": { "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" - } + "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes." }, - "html_content": { - "type": "string", - "description": "The HTML content of this campaign." + "enabled": { + "type": "boolean", + "description": "Indicates if the certificate is enabled." }, - "plain_content": { + "integration_id": { "type": "string", - "description": "The plain content of this campaign." + "description": "An ID that matches a certificate to a specific IdP integration. This is the `id` returned by the \"Get All SSO Integrations\" endpoint." } }, "required": [ - "title", - "subject", - "categories", - "html_content", - "plain_content" + "public_certificate", + "integration_id" ], "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!" + "public_certificate": "", + "enabled": false, + "integration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } @@ -2687,511 +2031,442 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/campaign_response" + "$ref": "#/definitions/sso-certificate-body" }, "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" + "public_certificate": "", + "id": 66138975, + "not_before": 1621289880, + "not_after": 1621289880, + "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } }, "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.\"", + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" + } + } + } + }, + "/sso/integrations/{integration_id}/certificates": { + "parameters": [ + { + "name": "integration_id", + "in": "path", + "description": "An ID that matches a certificate to a specific IdP integration.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_sso-integrations-integration_id-certificates", + "summary": "Get All SSO Certificates by Integration", + "tags": [ + "Certificates" + ], + "description": "**This endpoint allows you to retrieve all your IdP configurations by configuration ID.**\n\nThe `integration_id` expected by this endpoint is the `id` returned in the response by the #endpoint:qv7RWLGAHninr8zdG endpoint.", + "responses": { + "200": { + "description": "", "schema": { - "type": "object" + "type": "array", + "items": { + "$ref": "#/definitions/sso-certificate-body" + } }, "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." - } - ] - } + "application/json": [ + { + "public_certificate": "", + "id": 66138975, + "not_before": 1621289880, + "not_after": 1621289880, + "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" + } + ] } }, + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" + } + } + } + }, + "/sso/certificates/{cert_id}": { + "parameters": [ + { + "name": "cert_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_sso-certificates-cert_id", + "summary": "Get an SSO Certificate", + "tags": [ + "Certificates" + ], + "description": "**This endpoint allows you to retrieve an individual SSO certificate.**", + "responses": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/sso-certificate-body" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "public_certificate": "", + "id": 66138975, + "not_before": 1621289880, + "not_after": 1621289880, + "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } }, + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, "403": { - "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" + } + } + }, + "patch": { + "operationId": "PATCH_sso-certificates-cert_id", + "summary": "Update SSO Certificate", + "tags": [ + "Certificates" + ], + "description": "**This endpoint allows you to update an existing certificate by ID.**\n\nYou can retrieve a certificate's ID from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint.", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { - "type": "object" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "You may only update a campaign when it is in draft mode." - } - ] + "type": "object", + "properties": { + "public_certificate": { + "type": "string", + "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes." + }, + "enabled": { + "type": "boolean", + "description": "Indicates whether or not the certificate is enabled." + }, + "integration_id": { + "type": "string", + "description": "An ID that matches a certificate to a specific IdP integration." + } + }, + "example": { + "public_certificate": "", + "enabled": false, + "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } + } + ], + "responses": { + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" }, - "404": { - "description": "\"\": \"not found\"", + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" + } + } + }, + "delete": { + "operationId": "DELETE_sso-certificates-cert_id", + "summary": "Delete an SSO Certificate", + "tags": [ + "Certificates" + ], + "description": "**This endpoint allows you to delete an SSO certificate.**\n\nYou can retrieve a certificate's ID from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint.", + "responses": { + "200": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/sso-certificate-body" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] + "public_certificate": "", + "id": 66138975, + "not_before": 1621289880, + "not_after": 1621289880, + "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } + }, + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" } - }, - "security": [ - { - "Authorization": [] - } - ] + } } }, - "/campaigns/{campaign_id}/schedules/now": { - "parameters": [ - { - "name": "campaign_id", - "in": "path", - "required": true, - "type": "integer" - } - ], + "/sso/integrations": { "post": { - "operationId": "POST_campaigns-campaign_id-schedules-now", - "summary": "Send a Campaign", + "operationId": "POST_sso-integrations", + "summary": "Create an SSO Integration", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to immediately send a campaign at the time you make the API call.**\n\nNormally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "produces": [ - "application/json" + "Single Sign-On Settings" ], + "description": "**This endpoint allows you to create an SSO integration.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "$ref": "#/definitions/create-integration-request", + "example": { + "name": "Twilio SendGrid", + "enabled": true, + "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", + "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", + "entity_id": "http://www.okta.com/${org.externalKey}", + "completed_integration": true, + "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" + } } } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "title": "Send a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "status": { - "type": "string" - } - }, - "required": [ - "id", - "status" - ] + "$ref": "#/definitions/sso-integration" }, "examples": { "application/json": { - "id": 1234, - "status": "Scheduled" + "name": "Twilio SendGrid", + "enabled": true, + "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", + "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", + "entity_id": "http://www.okta.com/${org.externalKey}", + "last_updated": 1621288964 } } }, "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" - } - ] - } - } + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" }, "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." - } - ] - } - } + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" }, - "404": { - "description": "\"\": \"not found\"", + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" + } + } + }, + "get": { + "operationId": "GET_sso-integrations", + "summary": "Get All SSO Integrations", + "tags": [ + "Single Sign-On Settings" + ], + "description": "**This endpoint allows you to retrieve all SSO integrations tied to your Twilio SendGrid account.**\n\nThe IDs returned by this endpoint can be used by the APIs additional endpoints to modify your SSO integrations.", + "parameters": [ + { + "name": "si", + "in": "query", + "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", + "type": "boolean" + } + ], + "responses": { + "200": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "array", + "items": { + "$ref": "#/definitions/sso-integration" + } }, "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } + "application/json": [ + { + "name": "Twilio SendGrid", + "enabled": true, + "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", + "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", + "entity_id": "http://www.okta.com/${org.externalKey}", + "last_updated": 1621288520, + "completed_integration": true, + "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", + "single_signon_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312", + "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" + } + ] } + }, + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" } - }, - "security": [ - { - "Authorization": [] - } - ] + } } }, - "/campaigns/{campaign_id}/schedules": { + "/sso/integrations/{id}": { "parameters": [ { - "name": "campaign_id", + "name": "id", "in": "path", "required": true, - "type": "integer" + "type": "string" } ], - "post": { - "operationId": "POST_campaigns-campaign_id-schedules", - "summary": "Schedule a Campaign", + "get": { + "operationId": "GET_sso-integrations-id", + "summary": "Get an SSO Integration", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Single Sign-On Settings" ], + "description": "**This endpoint allows you to retrieve an SSO integration by ID.**\n\nYou can retrieve the IDs for your configurations from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "title": "Schedule a Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "description": "The unix timestamp for the date and time you would like your campaign to be sent out." - } - }, - "required": [ - "send_at" - ], - "example": { - "send_at": 1489771528 - } - } + "name": "si", + "in": "query", + "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", + "type": "boolean" } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "title": "Schedule a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID." - }, - "send_at": { - "type": "integer", - "description": "The date time you scheduled your campaign to be sent." - }, - "status": { - "type": "string", - "description": "The status of your campaign.", - "enum": [ - "Scheduled" - ] - } - }, - "required": [ - "id", - "send_at", - "status" - ] + "$ref": "#/definitions/sso-integration" }, "examples": { "application/json": { - "id": 1234, - "send_at": 1489771528, - "status": "Scheduled" + "name": "Twilio SendGrid", + "enabled": true, + "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", + "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", + "entity_id": "http://www.okta.com/${org.externalKey}", + "last_updated": 1621288964, + "completed_integration": true, + "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", + "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" } } }, "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" - } - ] - } - } + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" }, "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." - } - ] - } - } + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" } - ] + } }, "patch": { - "operationId": "PATCH_campaigns-campaign_id-schedules", - "summary": "Update a Scheduled Campaign", + "operationId": "PATCH_sso-integrations-id", + "summary": "Update an SSO Integration", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Single Sign-On Settings" ], + "description": "**This endpoint allows you to modify an exisiting SSO integration.**\n\nYou can retrieve the IDs for your configurations from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint.", "parameters": [ + { + "name": "si", + "in": "query", + "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", + "type": "boolean" + }, { "name": "body", "in": "body", "schema": { - "title": "Update a Scheduled Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": [ - "send_at" - ], + "$ref": "#/definitions/create-integration-request", "example": { - "send_at": 1489451436 + "name": "Twilio SendGrid", + "enabled": true, + "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", + "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", + "entity_id": "http://www.okta.com/${org.externalKey}", + "last_updated": 1621288964, + "completed_integration": true } } } @@ -3200,247 +2475,150 @@ "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" + "$ref": "#/definitions/sso-integration" }, "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" - } - ] + "name": "Twilio SendGrid", + "enabled": true, + "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", + "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", + "entity_id": "http://www.okta.com/${org.externalKey}", + "last_updated": 1621288964, + "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", + "single_signon_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312", + "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" } } }, + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, "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." - } - ] - } - } + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" } - ] + } }, - "get": { - "operationId": "GET_campaigns-campaign_id-schedules", - "summary": "View Scheduled Time of a Campaign", + "delete": { + "operationId": "DELETE_sso-integrations-id", + "summary": "Delete an SSO Integration", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "produces": [ - "application/json" + "Single Sign-On Settings" ], + "description": "**This endpoint allows you to delete an IdP configuration by ID.**\n\nYou can retrieve the IDs for your configurations from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint.", "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 - } - } + "204": { + "description": "" }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" } - ] - }, - "delete": { - "operationId": "DELETE_campaigns-campaign_id-schedules", - "summary": "Unschedule a Scheduled Campaign", + } + } + }, + "/sso/teammates": { + "post": { + "operationId": "POST_sso-teammates", + "summary": "Create SSO Teammate", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", - "produces": [ - "application/json" + "Single Sign-On Teammates" ], + "description": "**This endpoint allows you to create an SSO Teammate.**\n\nThe email provided for this user will also function as the Teammate’s username.", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "$ref": "#/definitions/sso-teammate-request", + "example": { + "first_name": "Jane", + "last_name": "Doe", + "email": "jane_doe@example.com", + "scopes": [ + "mail.batch.create", + "mail.batch.delete", + "mail.batch.read", + "mail.batch.update", + "mail.send" + ] + } } } ], "responses": { - "204": { + "201": { "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" + "$ref": "#/definitions/sso-teammate-response" }, "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." - } - ] + "first_name": "Jane", + "last_name": "Doe", + "email": "jane_doe@example.com", + "is_read_only": true, + "username": "jane_doe@example.com", + "is_sso": true } } }, - "404": { - "description": "\"\": \"not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" } - ] + } } }, - "/campaigns/{campaign_id}/schedules/test": { + "/sso/teammates/{username}": { "parameters": [ { - "name": "campaign_id", + "name": "username", "in": "path", + "description": "This email address must be the same address assigned to the teammate in your IdP", "required": true, - "type": "integer" + "type": "string", + "format": "email" } ], - "post": { - "operationId": "POST_campaigns-campaign_id-schedules-test", - "summary": "Send a Test Campaign", + "patch": { + "operationId": "PATCH_sso-teammates-username", + "summary": "Edit an SSO Teammate", "tags": [ - "Campaigns API" - ], - "description": "**This endpoint allows you to send a test campaign.**\n\nTo 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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Single Sign-On Teammates" ], + "description": "**This endpoint allows you to modify an existing SSO Teammate.**\n\nTo turn a teammate into an admin, the request body should contain the `is_admin` field set to `true`. Otherwise, set `is_admin` to false and pass in all the scopes that a teammate should have.\n\nOnly the parent user and Teammates with admin permissions can update another Teammate’s permissions. Admin users can only update permissions.", "parameters": [ { "name": "body", @@ -3448,76 +2626,223 @@ "schema": { "type": "object", "properties": { - "to": { - "type": "string", - "description": "The email address that should receive the test campaign.", - "format": "email" + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "scopes": { + "type": "array", + "items": { + "type": "string" + } + }, + "is_admin": { + "type": "boolean" } }, - "required": [ - "to" - ], "example": { - "to": "your.email@example.com" + "first_name": "Jane", + "last_name": "Doe", + "email": "jane_doe@example.com", + "scopes": [ + "mail.batch.create", + "mail.batch.delete", + "mail.batch.read", + "mail.batch.update", + "mail.send" + ], + "is_admin": false } } } ], "responses": { - "204": { + "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.\"\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" + "$ref": "#/definitions/sso-teammates-patch-response" }, "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" - } - ] + "first_name": "Jane", + "last_name": "Doe", + "email": "jane_doe@example.com", + "is_admin": false, + "username": "jane_doe@example.com", + "is_sso": true, + "address": "1234 Fake St.", + "address2": "Suite 5", + "city": "San Francisco", + "state": "CA", + "zip": "94105", + "Country": "United States", + "phone": "+15555555555", + "user_type": "teammate" } } }, - "404": { - "description": "\"\": \"not found\"", + "400": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:400" + }, + "401": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:401" + }, + "403": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:403" + }, + "429": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:429" + }, + "500": { + "$ref": "#/responses/trait:singleSignOnErrorsTrait:500" + } + } + } + }, + "/mail_settings": { + "get": { + "operationId": "GET_mail_settings", + "summary": "Retrieve all mail settings", + "tags": [ + "Settings - Mail" + ], + "description": "**This endpoint allows you to retrieve a list of all mail settings.**\n\nEach setting will be returned with an `enabled` status set to `true` or `false` and a short description that explains what the setting does.", + "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" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "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": { - "errors": [ + "result": [ { - "field": null, - "message": "not found" + "title": "Address Whitelist", + "enabled": false, + "name": "address_whitelist", + "description": "Address / domains that should never have email suppressed." + }, + { + "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." } ] } } + }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -3527,53 +2852,75 @@ ] } }, - "/mail/batch": { - "post": { - "operationId": "POST_mail-batch", - "summary": "Create a batch ID", + "/mail_settings/address_whitelist": { + "patch": { + "operationId": "PATCH_mail_settings-address_whitelist", + "summary": "Update address whitelist mail settings", "tags": [ - "Cancel Scheduled Sends" - ], - "description": "**This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.**\n\nIf you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", - "produces": [ - "application/json" + "Settings - Mail" ], + "description": "**This endpoint allows you to update your current email address whitelist settings.**\n\nYou can select whether or not this setting should be enabled by assigning the `enabled` field a `true` or `false` value.\n\nPassing only the `enabled` field to this endpoint will not alter your current `list` of whitelist entries. However, any modifications to your `list` of entries will overwrite the entire list. For this reason, you must included all existing entries you wish to retain in your `list` in addition to any new entries you intend to add. To remove one or more `list` entries, pass a `list` with only the entries you wish to retain.\n\nYou should not add generic domains such as `gmail.com` or `yahoo.com` in your `list` because your emails will not honor recipients' unsubscribes. This may cause a legal violation of [CAN-SPAM](https://sendgrid.com/docs/glossary/can-spam/) and could damage your sending reputation.\n\nThe Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed.\n\nFor example, if you own the domain `example.com`, and one or more of your recipients use `email@example.com` addresses, placing `example.com` in the address whitelist setting instructs Twilio SendGrid to ignore all bounces, blocks, and unsubscribes logged for that domain. In other words, all bounces, blocks, and unsubscribes will still be sent to `example.com` as if they were sent under normal sending conditions.", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "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" + } + } + }, + "example": { + "enabled": true, + "list": [ + "email1@example.com", + "example.com" + ] + } } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_batch_id" + "$ref": "#/definitions/mail_settings_address_whitelabel" }, "examples": { "application/json": { - "batch_id": "YOUR_BATCH_ID" + "enabled": true, + "list": [ + "email1@example.com" + ] } } }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -3581,70 +2928,49 @@ "Authorization": [] } ] - } - }, - "/mail/batch/{batch_id}": { - "parameters": [ - { - "name": "batch_id", - "in": "path", - "required": true, - "type": "string" - } - ], + }, "get": { - "operationId": "GET_mail-batch-batch_id", - "summary": "Validate batch ID", + "operationId": "GET_mail_settings-address_whitelist", + "summary": "Retrieve address whitelist mail settings", "tags": [ - "Cancel Scheduled Sends" + "Settings - Mail" ], - "description": "**This endpoint allows you to validate a batch ID.**\n\nIf you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. \n\nMore Information:\n\n* [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html)", - "produces": [ - "application/json" + "description": "**This endpoint allows you to retrieve your current email address whitelist settings.**\n\nThe Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed.\n\nFor example, if you own the domain `example.com`, and one or more of your recipients use `email@example.com` addresses, placing `example.com` in the address whitelist setting instructs Twilio SendGrid to ignore all bounces, blocks, and unsubscribes logged for that domain. In other words, all bounces, blocks, and unsubscribes will still be sent to `example.com` as if they were sent under normal sending conditions.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_batch_id" + "$ref": "#/definitions/mail_settings_address_whitelabel" }, "examples": { "application/json": { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" + "enabled": true, + "list": [ + "example.com", + "jane_doe@example1.com" + ] } } }, "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "invalid batch id" - } - ] - } - } + "$ref": "#/responses/trait:makoErrorResponse:400" }, "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" - } - ] - } - } + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -3654,100 +2980,59 @@ ] } }, - "/user/scheduled_sends": { - "post": { - "operationId": "POST_user-scheduled_sends", - "summary": "Cancel or pause a scheduled send", + "/mail_settings/footer": { + "patch": { + "operationId": "PATCH_mail_settings-footer", + "summary": "Update footer mail settings", "tags": [ - "Cancel Scheduled Sends" - ], - "description": "**This endpoint allows you to cancel or pause an email that has been scheduled to be sent.**\n\nIf 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.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Settings - Mail" ], + "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 your text and HTML email message bodies.\n\nYou can insert your HTML or plain text directly using this endpoint, or you can create the footer using the [Mail Settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", "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" - ], + "$ref": "#/definitions/mail_settings_footer", "example": { - "batch_id": "YOUR_BATCH_ID", - "status": "pause" + "enabled": true, + "html_content": "

Ahoy, World!

\n", + "plain_content": "" } } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "201": { + "200": { "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" + "$ref": "#/definitions/mail_settings_footer" }, "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" - } - ] + "enabled": true, + "html_content": "

Ahoy, World!

\n", + "plain_content": "" } } }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, "401": { - "description": "", - "schema": { - "type": "object" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -3757,52 +3042,45 @@ ] }, "get": { - "operationId": "GET_user-scheduled_sends", - "summary": "Retrieve all scheduled sends", + "operationId": "GET_mail_settings-footer", + "summary": "Retrieve footer mail settings", "tags": [ - "Cancel Scheduled Sends" + "Settings - Mail" ], - "description": "**This endpoint allows you to retrieve all cancel/paused scheduled send information.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "produces": [ - "application/json" + "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 your text and HTML email message bodies.\n\nYou can insert your HTML or plain text directly using the #endpoint:LPTaj7czYsMS8spND, or you can create the footer using the [Mail Settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "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" + "$ref": "#/definitions/mail_settings_footer" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "enabled": true, + "html_content": "

Ahoy, World!

\n", + "plain_content": "" } } + }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -3812,63 +3090,57 @@ ] } }, - "/user/scheduled_sends/{batch_id}": { - "parameters": [ - { - "name": "batch_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_user-scheduled_sends-batch_id", - "summary": "Retrieve scheduled send", + "/mail_settings/forward_spam": { + "patch": { + "operationId": "PATCH_mail_settings-forward_spam", + "summary": "Update forward spam mail settings", "tags": [ - "Cancel Scheduled Sends" - ], - "description": "**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "produces": [ - "application/json" + "Settings - Mail" ], - "responses": { - "200": { - "description": "", + "description": "**This endpoint allows you to update your current Forward Spam mail settings.**\n\nEnabling the Forward Spam setting allows you to specify `email` addresses to which spam reports will be forwarded. You can set multiple addresses by passing this endpoint a comma separated list of emails in a single string.\n\n```\n{\n \"email\": \"address1@example.com, address2@exapmle.com\",\n \"enabled\": true\n}\n```\n\nThe Forward Spam setting may also be used to receive emails sent to `abuse@` and `postmaster@` role addresses if you have authenticated your domain.\n\nFor example, if you authenticated `example.com` as your root domain and set a custom return path of `sub` for that domain, you could turn on Forward Spam, and any emails sent to `abuse@sub.example.com` or `postmaster@sub.example.com` would be forwarded to the email address you entered in the `email` field.\n\nYou can authenticate your domain using the #endpoint:aXpkWYramCg4ZNEGT endpoint or in the [Sender Authentication section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth). You can also configure the Forward Spam mail settings in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { - "type": "array", - "title": "Retrieve scheduled send response", - "items": { - "$ref": "#/definitions/user_scheduled_send_status" + "$ref": "#/definitions/mail_settings_forward_spam", + "example": { + "email": "abuse@example.com", + "enabled": true } - }, - "examples": { - "application/json": [ - { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", - "status": "cancel" - }, - { - "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", - "status": "pause" - } - ] } }, - "401": { + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/mail_settings_forward_spam" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "email": "abuse@example.com", + "enabled": true } } + }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -3877,98 +3149,176 @@ } ] }, - "patch": { - "operationId": "PATCH_user-scheduled_sends-batch_id", - "summary": "Update user scheduled send information", + "get": { + "operationId": "GET_mail_settings-forward_spam", + "summary": "Retrieve forward spam mail settings", "tags": [ - "Cancel Scheduled Sends" - ], - "description": "**This endpoint allows you to update the status of a scheduled send for the given `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.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Settings - Mail" ], + "description": "**This endpoint allows you to retrieve your current Forward Spam mail settings.**\n\nEnabling the Forward Spam setting allows you to specify `email` addresses to which spam reports will be forwarded. This endpoint returns any email address(es) you have set to receive forwarded spam and an `enabled` status indicating if the setting is active.", "parameters": [ { - "name": "body", - "in": "body", + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", "schema": { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status you would like the scheduled send to have.", - "enum": [ - "cancel", - "pause" - ] + "$ref": "#/definitions/mail_settings_forward_spam" + }, + "examples": { + "application/json": { + "email": "abuse@example.com", + "enabled": true + } + } + }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/mail_settings/template": { + "patch": { + "operationId": "PATCH_mail_settings-template", + "summary": "Update template mail settings", + "tags": [ + "Settings - Mail" + ], + "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 [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).\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. For instructions on using legacy templates, see how to [\"Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see [\"Migrating from Legacy Templates\"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/).", + "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." } }, - "required": [ - "status" - ], "example": { - "status": "pause" + "enabled": true, + "html_content": "<% body %>" } } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "400": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the legacy email template mail setting is enabled." + }, + "html_content": { + "type": "string", + "description": "The HTML content of your legacy email template." + } + }, + "required": [ + "enabled", + "html_content" + ] }, "examples": { "application/json": { - "errors": [ - { - "field": "status", - "message": "status must be either cancel or pause" - } - ] + "enabled": false, + "html_content": "

<% body %>Example

\n" } } }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_mail_settings-template", + "summary": "Retrieve legacy template mail settings", + "tags": [ + "Settings - Mail" + ], + "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 [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).\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. For instructions on using legacy templates, see how to [\"Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see [\"Migrating from Legacy Templates\"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/).", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/mail_settings_template" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "enabled": false, + "html_content": "

<% body %>Example

\n" } } }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, "404": { - "description": "\"\" : \"batch id not found\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] - } - } + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -3976,64 +3326,61 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_user-scheduled_sends-batch_id", - "summary": "Delete a cancellation or pause of a scheduled send", + } + }, + "/mail_settings/bounce_purge": { + "patch": { + "operationId": "PATCH_mail_settings-bounce_purge", + "summary": "Update bounce purge mail settings", "tags": [ - "Cancel Scheduled Sends" - ], - "description": "**This endpoint allows you to delete the cancellation/pause of a scheduled send.**\n\nThe Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.", - "produces": [ - "application/json" + "Settings - Mail" ], + "description": "**This endpoint allows you to update your current bounce and purge settings.**\n\nThe Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists. The schedule is set in full days by assigning the number of days, an integer, to the `soft_bounces` and/or `hard_bounces` fields.\n\nA hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown.\n\nA soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full.\n\nYou can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "$ref": "#/definitions/mail_settings_bounce_purge", + "example": { + "enabled": true, + "hard_bounces": 5, + "soft_bounces": 5 + } } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - }, - "401": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/mail_settings_bounce_purge" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "enabled": false, + "hard_bounces": 5, + "soft_bounces": 5 } } }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, "404": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "batch id not found" - } - ] - } - } + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -4041,40 +3388,15 @@ "Authorization": [] } ] - } - }, - "/categories": { + }, "get": { - "operationId": "GET_categories", - "summary": "Retrieve all categories", + "operationId": "GET_mail_settings-bounce_purge", + "summary": "Retrieve bounce purge mail settings", "tags": [ - "Categories" - ], - "description": "**This endpoint allows you to retrieve a list of all of your categories.**\n\nCategories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html).", - "produces": [ - "application/json" + "Settings - Mail" ], + "description": "**This endpoint allows you to retrieve your current bounce and purge settings.**\n\nThe Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists.\n\nA hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown.\n\nA soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full.\n\nYou can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of categories to display per page.", - "type": "integer", - "default": 50 - }, - { - "name": "category", - "in": "query", - "description": "Allows you to perform a prefix search on this particular category.", - "type": "string" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list that you would like to begin displaying results.", - "type": "integer", - "default": 0 - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -4083,68 +3405,90 @@ "200": { "description": "", "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "category": { - "type": "string", - "description": "A category used to group emails by broad topic." - } - }, - "required": [ - "category" - ] - } + "$ref": "#/definitions/mail_settings_bounce_purge" }, "examples": { - "application/json": [ - { - "category": "category 1" - }, - { - "category": "category 2" - } - ] + "application/json": { + "enabled": false, + "soft_bounces": 5, + "hard_bounces": 5 + } } }, "400": { - "description": "", + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/mail_settings/forward_bounce": { + "patch": { + "operationId": "PATCH_mail_settings-forward_bounce", + "summary": "Update forward bounce mail settings", + "tags": [ + "Settings - Mail" + ], + "description": "**This endpoint allows you to update your current bounce forwarding mail settings.**\n\nEnabling the Forward Bounce setting allows you to specify an `email` address to which bounce reports will be forwarded.\n\nYou can also configure the Forward Spam mail settings in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The error returned.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "message": { - "type": "string", - "description": "A message explaining why your categories could not be retrieved." - } - }, - "required": [ - "field", - "message" - ] - } - } + "$ref": "#/definitions/mail_settings_forward_bounce", + "example": { + "enabled": true, + "email": "bounces@example.com" } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/mail_settings_forward_bounce" }, "examples": { "application/json": { - "errors": [ - { - "field": "sort_by", - "message": "invalid sort value" - } - ] + "email": "bounces@example.com", + "enabled": true } } + }, + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" + }, + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" + }, + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" + }, + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" + }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ @@ -4152,81 +3496,89 @@ "Authorization": [] } ] - } - }, - "/categories/stats/sums": { + }, "get": { - "operationId": "GET_categories-stats-sums", - "summary": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", + "operationId": "GET_mail_settings-forward_bounce", + "summary": "Retrieve forward bounce mail settings", "tags": [ - "Categories" - ], - "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).", - "produces": [ - "application/json" + "Settings - Mail" ], + "description": "**This endpoint allows you to retrieve your current bounce forwarding mail settings.**\n\nEnabling the Forward Bounce setting allows you to specify `email` addresses to which bounce reports will be forwarded. This endpoint returns the email address you have set to receive forwarded bounces and an `enabled` status indicating if the setting is active.", "parameters": [ { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Must be a single metric.", - "required": false, - "type": "string", - "default": "delivered" + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/mail_settings_forward_bounce" + }, + "examples": { + "application/json": { + "enabled": true, + "email": "bounces@example.com" + } + } }, - { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort.", - "required": false, - "type": "string", - "default": "desc", - "enum": [ - "desc", - "asc" - ] + "400": { + "$ref": "#/responses/trait:makoErrorResponse:400" }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" + "401": { + "$ref": "#/responses/trait:makoErrorResponse:401" }, - { - "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" + "403": { + "$ref": "#/responses/trait:makoErrorResponse:403" }, - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned.", - "required": false, - "type": "integer", - "default": 5 + "404": { + "$ref": "#/responses/trait:makoErrorResponse:404" }, + "500": { + "$ref": "#/responses/trait:makoErrorResponse:500" + } + }, + "security": [ { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results.", - "required": false, - "type": "integer", - "default": 0 - }, + "Authorization": [] + } + ] + } + }, + "/partner_settings/new_relic": { + "patch": { + "operationId": "PATCH_partner_settings-new_relic", + "summary": "Updates New Relic partner settings.", + "tags": [ + "Settings - Partner" + ], + "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 [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).\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 [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/).", + "parameters": [ { - "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": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "license_key": { + "type": "string", + "description": "The license key for your New Relic account." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if this partner setting is enabled." + }, + "enable_subuser_statistics": { + "type": "boolean", + "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." + } + }, + "example": { + "license_key": "", + "enabled": true, + "enable_subuser_statistics": true + } + } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -4236,123 +3588,13 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/category_stats" + "$ref": "#/definitions/partner_settings_new_relic" }, "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" - } - ] + "enable_subuser_statistics": true, + "enabled": true, + "license_key": "" } } } @@ -4362,69 +3604,15 @@ "Authorization": [] } ] - } - }, - "/categories/stats": { + }, "get": { - "operationId": "GET_categories-stats", - "summary": "Retrieve Email Statistics for Categories", + "operationId": "GET_partner_settings-new_relic", + "summary": "Returns all New Relic partner settings.", "tags": [ - "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).", - "produces": [ - "application/json" + "Settings - Partner" ], + "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 [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).\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 [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/).", "parameters": [ - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" - }, - { - "name": "categories", - "in": "query", - "description": "The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.", - "required": true, - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "The number of results to include.", - "required": false, - "type": "integer", - "default": 500, - "maximum": 500 - }, - { - "name": "offset", - "in": "query", - "description": "The number of results to skip.", - "required": false, - "type": "integer" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -4433,112 +3621,14 @@ "200": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/category_stats" - } + "$ref": "#/definitions/partner_settings_new_relic" }, "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 - } - } - ] - } - ] + "application/json": { + "enable_subuser_statistics": false, + "enabled": true, + "license_key": "" + } } } }, @@ -4549,20 +3639,98 @@ ] } }, - "/contactdb/custom_fields": { - "post": { - "operationId": "POST_contactdb-custom_fields", - "summary": "Create a Custom Field", + "/partner_settings": { + "get": { + "operationId": "GET_partner_settings", + "summary": "Returns a list of all partner settings.", "tags": [ - "Contacts API - Custom Fields" + "Settings - Partner" ], - "description": "**This endpoint allows you to 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).", - "consumes": [ - "application/json" + "description": "**This endpoint allows you to retrieve a list of all partner settings that you can enable.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).", + "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" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], - "produces": [ - "application/json" + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The title of the partner." + }, + "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." + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/teammates": { + "post": { + "operationId": "POST_v3-teammates", + "summary": "Invite teammate", + "tags": [ + "Teammates" ], + "description": "**This endpoint allows you to invite a Teammate to your account via email.**\n\nYou can set a Teammate's initial permissions using the `scopes` array in the request body. Teammate's will receive a minimum set of scopes from Twilio SendGrid that are necessary for the Teammate to function.\n\n**Note:** A teammate invite will expire after 7 days, but you may resend the invitation at any time to reset the expiration date.", "parameters": [ { "name": "body", @@ -4570,16 +3738,38 @@ "schema": { "type": "object", "properties": { - "name": { - "type": "string" + "email": { + "type": "string", + "description": "New teammate's email", + "minLength": 5, + "maxLength": 255, + "pattern": "^.*@.*\\..*" }, - "type": { - "type": "string" + "scopes": { + "type": "array", + "description": "Set to specify list of scopes that teammate should have. Should be empty if teammate is an admin.", + "items": { + "type": "string" + } + }, + "is_admin": { + "type": "boolean", + "default": false, + "description": "Set to true if teammate should be an admin user" } }, + "required": [ + "email", + "scopes", + "is_admin" + ], "example": { - "name": "pet", - "type": "text" + "email": "teammate1@example.com", + "scopes": [ + "user.profile.read", + "user.profile.update" + ], + "is_admin": false } } }, @@ -4593,46 +3783,55 @@ "schema": { "type": "object", "properties": { - "id": { - "type": "integer" + "token": { + "type": "string", + "description": "Token to identify invite" }, - "name": { - "type": "string" + "email": { + "type": "string", + "description": "Teammate's email address" }, - "type": { - "type": "string" + "scopes": { + "type": "array", + "description": "Initial set of permissions to give to teammate if they accept the invite", + "items": {} + }, + "is_admin": { + "type": "boolean", + "description": "Set to true if teammate should have admin privileges" } } }, "examples": { "application/json": { - "id": 1, - "name": "pet", - "type": "text" + "email": "teammate1@example.com", + "scopes": [ + "user.profile.read", + "user.profile.update" + ], + "is_admin": false } } }, "400": { - "description": "\"\" : \"Returned if request body is invalid JSON\"\n\"type\" : \"Returned if custom field type is invalid or not provided\"\n\"name\" : \"Returned if custom field name is not provided\"", + "description": "", "schema": { - "$ref": "#/definitions/errors" - }, - "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" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } - ] + } } } } @@ -4644,16 +3843,30 @@ ] }, "get": { - "operationId": "GET_contactdb-custom_fields", - "summary": "Retrieve all custom fields", + "operationId": "GET_v3-teammates", + "summary": "Retrieve all teammates", "tags": [ - "Contacts API - Custom Fields" - ], - "description": "**This endpoint allows you to retrieve all custom fields.** \n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to retrieve a list of all current Teammates.**\n\nYou can limit the number of results returned using the `limit` query paramater. To return results from a specific Teammate, use the `offset` paramter. The Response Headers will include pagination info.", "parameters": [ + { + "name": "limit", + "in": "query", + "description": "Number of items to return", + "type": "integer", + "default": 500, + "minimum": 0, + "maximum": 500 + }, + { + "name": "offset", + "in": "query", + "description": "Paging offset", + "type": "integer", + "default": 0, + "minimum": 0 + }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -4662,68 +3875,132 @@ "200": { "description": "", "schema": { - "title": "List All Custom Fields response", "type": "object", "properties": { - "custom_fields": { + "result": { "type": "array", "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id" - } - } - }, - "required": [ - "custom_fields" - ] - }, - "examples": { - "application/json": { - "custom_fields": [ - { - "id": 6234, - "name": "age", - "type": "number" - }, - { - "id": 6233, - "name": "country", - "type": "text" - }, - { - "id": 6235, - "name": "favorite_color", - "type": "text" - }, - { - "id": 6239, - "name": "fname", - "type": "text" - }, - { - "id": 6240, - "name": "lname", - "type": "text" - }, - { - "id": 49439, - "name": "pet", - "type": "text" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "Teammate's username" + }, + "email": { + "type": "string", + "description": "Teammate's email" + }, + "first_name": { + "type": "string", + "description": "Teammate's first name" + }, + "last_name": { + "type": "string", + "description": "Teammate's last name" + }, + "user_type": { + "type": "string", + "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", + "enum": [ + "admin", + "owner", + "teammate" + ] + }, + "is_admin": { + "type": "boolean", + "description": "Set to true if teammate has admin privileges" + }, + "phone": { + "type": "string", + "description": "(optional) Teammate's phone number" + }, + "website": { + "type": "string", + "description": "(optional) Teammate's website" + }, + "address": { + "type": "string", + "description": "(optional) Teammate's address" + }, + "address2": { + "type": "string", + "description": "(optional) Teammate's address" + }, + "city": { + "type": "string", + "description": "(optional) Teammate's city" + }, + "state": { + "type": "string", + "description": "(optional) Teammate's state" + }, + "zip": { + "type": "string", + "description": "(optional) Teammate's zip" + }, + "country": { + "type": "string", + "description": "(optional) Teammate's country" + } + } + } + } + } }, "examples": { "application/json": { - "errors": [ + "results": [ { - "field": null, - "message": "authorization required" + "username": "teammate1", + "email": "teammate1@example.com", + "first_name": "Jane", + "last_name": "Doe", + "user_type": "owner", + "is_admin": true, + "phone": "123-345-3453", + "website": "www.example.com", + "company": "ACME Inc.", + "address": "123 Acme St", + "address2": "", + "city": "City", + "state": "CA", + "country": "USA", + "zip": "12345" + }, + { + "username": "teammate2", + "email": "teammate2@example.com", + "first_name": "John", + "last_name": "Doe", + "user_type": "teammate", + "is_admin": false, + "phone": "123-345-3453", + "website": "www.example.com", + "company": "ACME Inc.", + "address": "123 Acme St", + "address2": "", + "city": "City", + "state": "CA", + "country": "USA", + "zip": "12345" + }, + { + "username": "teammate3", + "email": "teammate3@example.com", + "first_name": "Steve", + "last_name": "Doe", + "user_type": "admin", + "is_admin": true, + "phone": "123-345-3453", + "website": "www.example.com", + "company": "ACME Inc.", + "address": "123 Acme St", + "address2": "", + "city": "City", + "state": "CA", + "country": "USA", + "zip": "12345" } ] } @@ -4737,26 +4014,23 @@ ] } }, - "/contactdb/custom_fields/{custom_field_id}": { + "/teammates/pending/{token}/resend": { "parameters": [ { - "name": "custom_field_id", + "name": "token", "in": "path", - "description": "The ID of the custom field that you want to retrieve.", + "description": "The token for the invite that you want to resend.", "required": true, - "type": "integer" + "type": "string" } ], - "get": { - "operationId": "GET_contactdb-custom_fields-custom_field_id", - "summary": "Retrieve a Custom Field", + "post": { + "operationId": "POST_v3-teammates-pending-token-resend", + "summary": "Resend teammate invite", "tags": [ - "Contacts API - Custom Fields" - ], - "description": "**This endpoint allows you to retrieve a custom field by ID.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to resend a Teammate invitation.**\n\nTeammate invitations will expire after 7 days. Resending an invitation will reset the expiration date.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -4766,57 +4040,68 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/contactdb_custom_field_with_id" - }, - "examples": { - "application/json": { - "id": 1, - "name": "pet", - "type": "text" + "type": "object", + "properties": { + "token": { + "type": "string", + "description": "ID to identify invite" + }, + "email": { + "type": "string", + "description": "Teammate's email address" + }, + "scopes": { + "type": "array", + "description": "Initial set of permissions to give to teammate if they accept the invite", + "items": { + "type": "string" + } + }, + "is_admin": { + "type": "boolean", + "description": "Set to true if teammate should have admin privileges" + } } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, "examples": { "application/json": { - "errors": [ - { - "message": "invalid id" - } - ] + "pending_id": "abc123abc", + "email": "teammate1@example.com", + "scopes": [ + "user.profile.read", + "user.profile.update" + ], + "is_admin": false } } }, - "401": { + "404": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } - ] + } } - } - }, - "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" + "message": "invalid pending key", + "field": "pending_key" } ] } @@ -4828,88 +4113,86 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_contactdb-custom_fields-custom_field_id", - "summary": "Delete a Custom Field", + } + }, + "/scopes/requests": { + "get": { + "operationId": "GET_v3-scopes-requests", + "summary": "Retrieve access requests", "tags": [ - "Contacts API - Custom Fields" - ], - "description": "**This endpoint allows you to delete a custom field by ID.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to retrieve a list of all recent access requests.**\n\nThe Response Header's `link` parameter will include pagination info.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + "name": "limit", + "in": "query", + "description": "Optional field to limit the number of results returned.", + "type": "integer", + "default": 50 }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "offset", + "in": "query", + "description": "Optional beginning point in the list to retrieve from.", + "type": "integer", + "default": 0 } ], "responses": { - "202": { + "200": { "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" + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Request ID" }, - { - "message": "Custom field ID does not exist" + "scope_group_name": { + "type": "string", + "description": "Name of group of scopes associated to page teammate is requesting access to" + }, + "username": { + "type": "string", + "description": "Teammate's username" + }, + "email": { + "type": "string", + "description": "Teammate's email" + }, + "first_name": { + "type": "string", + "description": "Teammate's first name" + }, + "last_name": { + "type": "string", + "description": "Teammate's last name" } - ] + } } - } - }, - "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" - } - ] - } + "application/json": [ + { + "id": 1, + "scope_group_name": "Mail Settings", + "username": "teammate1", + "email": "teammate1@example.com", + "first_name": "Teammate", + "last_name": "One" + }, + { + "id": 2, + "scope_group_name": "Stats", + "username": "teammate2", + "email": "teammate2@example.com", + "first_name": "Teammate", + "last_name": "Two" + } + ] } } }, @@ -4920,17 +4203,14 @@ ] } }, - "/contactdb/reserved_fields": { + "/teammates/pending": { "get": { - "operationId": "GET_contactdb-reserved_fields", - "summary": "Retrieve reserved fields", + "operationId": "GET_v3-teammates-pending", + "summary": "Retrieve all pending teammates", "tags": [ - "Contacts API - Custom Fields" - ], - "description": "**This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to retrieve a list of all pending Teammate invitations.**\n\nEach teammate invitation is valid for 7 days. Users may resend the invitation to refresh the expiration date.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -4940,75 +4220,60 @@ "200": { "description": "", "schema": { - "title": "List fields that are reserved and can't be used for custom field names. response", "type": "object", "properties": { - "reserved_fields": { + "result": { "type": "array", - "description": "The reserved fields that are already set up within custom fields.", "items": { - "$ref": "#/definitions/contactdb_custom_field" + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "Email address teammate invite will be sent to" + }, + "scopes": { + "type": "array", + "description": "List of permissions to give teammate if they accept", + "items": { + "type": "string" + } + }, + "is_admin": { + "type": "boolean", + "description": "Set to true to indicate teammate should have the same set of permissions as parent user" + }, + "token": { + "type": "string", + "description": "Invitation token used to identify user" + }, + "expiration_date": { + "type": "integer", + "description": "timestamp indicates when invite will expire. Expiration is 7 days after invite creation" + } + } } } - }, - "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" - }, + "result": [ { - "name": "last_opened", - "type": "date" + "email": "user1@example.com", + "scopes": [ + "user.profile.read", + "user.profile.edit" + ], + "is_admin": false, + "pending_id": "abcd123abc", + "expiration_date": 1456424263 }, { - "name": "my_custom_field", - "type": "text" - } - ] - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "email": "user2@example.com", + "scopes": [], + "is_admin": true, + "pending_id": "bcde234bcd", + "expiration_date": 1456424263 } ] } @@ -5022,147 +4287,124 @@ ] } }, - "/contactdb/lists": { - "post": { - "operationId": "POST_contactdb-lists", - "summary": "Create a List", + "/teammates/{username}": { + "parameters": [ + { + "name": "username", + "in": "path", + "description": "The username of the teammate that you want to retrieve.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_v3-teammates-username", + "summary": "Retrieve specific teammate", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to create a list for your recipients.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to retrieve a specific Teammate by username.**\n\nYou can retrieve the username's for each of your Teammates using the #endpoint:DiW4xbhq35GgRP6Mp endpoint.", "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "title": "Create a List request", - "type": "object", - "properties": { - "name": { - "type": "string" - } - }, - "required": [ - "name" - ], - "example": { - "name": "your list name" - } - } - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "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": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "operationId": "GET_contactdb-lists", - "summary": "Retrieve all lists", - "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "title": "List All Lists response", "type": "object", "properties": { - "lists": { + "username": { + "type": "string", + "description": "Teammate's username" + }, + "first_name": { + "type": "string", + "description": "Teammate's first name" + }, + "last_name": { + "type": "string", + "description": "Teammate's last name" + }, + "email": { + "type": "string", + "description": "Teammate's email" + }, + "scopes": { "type": "array", - "items": { - "$ref": "#/definitions/contactdb_list" - } + "description": "Scopes associated to teammate", + "items": {} + }, + "user_type": { + "type": "string", + "description": "Indicate the type of user: account owner, teammate admin user, or normal teammate", + "enum": [ + "admin", + "owner", + "teammate" + ] + }, + "is_admin": { + "type": "boolean", + "description": "Set to true if teammate has admin privileges" + }, + "phone": { + "type": "string", + "description": "(optional) Teammate's phone number" + }, + "website": { + "type": "string", + "description": "(optional) Teammate's website" + }, + "address": { + "type": "string", + "description": "(optional) Teammate's address" + }, + "address2": { + "type": "string", + "description": "(optional) Teammate's address" + }, + "city": { + "type": "string", + "description": "(optional) Teammate's city" + }, + "state": { + "type": "string", + "description": "(optional) Teammate's state" + }, + "zip": { + "type": "string", + "description": "(optional) Teammate's zip" + }, + "country": { + "type": "string", + "description": "(optional) Teammate's country" } - }, - "required": [ - "lists" - ] + } }, "examples": { "application/json": { - "lists": [ - { - "id": 1, - "name": "the jones", - "recipient_count": 1 - } - ] + "username": "teammate1", + "first_name": "Jane", + "last_name": "Doe", + "email": "teammate1@example.com", + "scopes": [ + "user.profile.read", + "user.profile.update", + "..." + ], + "user_type": "admin", + "is_admin": true, + "phone": "123-345-3453", + "website": "www.example.com", + "company": "ACME Inc.", + "address": "123 Acme St", + "address2": "", + "city": "City", + "state": "CA", + "country": "USA", + "zip": "12345" } } } @@ -5173,34 +4415,43 @@ } ] }, - "delete": { - "operationId": "DELETE_contactdb-lists", - "summary": "Delete Multiple lists", + "patch": { + "operationId": "PATCH_v3-teammates-username", + "summary": "Update teammate's permissions", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to delete multiple recipient lists.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to update a teammate’s permissions.**\n\nTo turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have.\n\n**Only the parent user or other admin teammates can update another teammate’s permissions.**\n\n**Admin users can only update permissions.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "array", - "items": { - "type": "integer" + "type": "object", + "properties": { + "scopes": { + "type": "array", + "description": "Provide list of scopes that should be given to teammate. If specifying list of scopes, is_admin should be set to False.", + "items": { + "type": "string" + } + }, + "is_admin": { + "type": "boolean", + "description": "Set to True if this teammate should be promoted to an admin user. If True, scopes should be an empty array." + } }, - "example": [ - 1, - 2, - 3, - 4 - ] + "required": [ + "scopes", + "is_admin" + ], + "example": { + "scopes": [ + "user.profile.read", + "user.profile.edit" + ], + "is_admin": false + } } }, { @@ -5208,138 +4459,164 @@ } ], "responses": { - "204": { + "200": { "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" + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "Teammate's username" + }, + "first_name": { + "type": "string", + "description": "Teammate's first name" + }, + "last_name": { + "type": "string", + "description": "Teammate's last name" + }, + "email": { + "type": "string", + "description": "Teammate's email address" + }, + "scopes": { + "type": "array", + "description": "Scopes given to teammate", + "items": { + "type": "string" } - ] + }, + "user_type": { + "type": "string", + "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", + "enum": [ + "admin", + "owner", + "teammate" + ] + }, + "is_admin": { + "type": "boolean", + "description": "Set to true if teammate has admin priveleges" + }, + "phone": { + "type": "string", + "description": "(optional) Teammate's phone number" + }, + "website": { + "type": "string", + "description": "(optional) Teammate's website" + }, + "address": { + "type": "string", + "description": "(optional) Teammate's address" + }, + "address2": { + "type": "string", + "description": "(optional) Teammate's address" + }, + "city": { + "type": "string", + "description": "(optional) Teammate's city" + }, + "state": { + "type": "string", + "description": "(optional) Teammate's state" + }, + "zip": { + "type": "string", + "description": "(optional) Teammate's zip" + }, + "country": { + "type": "string", + "description": "(optional) Teammate's country" + } } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/contactdb/lists/{list_id}": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_contactdb-lists-list_id", - "summary": "Retrieve a single list", - "tags": [ - "Contacts API - Lists" - ], - "description": "This endpoint allows you to retrieve a single recipient list.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list to retrieve.", - "type": "integer" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/contactdb_list" - }, - "examples": { - "application/json": { - "id": 1, - "name": "listname", - "recipient_count": 0 + "username": "teammate1", + "first_name": "Jane", + "last_name": "Doe", + "email": "teammate1@example.com", + "scopes": [ + "user.profile.read", + "user.profile.edit" + ], + "user_type": "teammate", + "is_admin": false, + "phone": "123-345-3453", + "website": "www.example.com", + "company": "ACME Inc.", + "address": "123 Acme St", + "address2": "", + "city": "City", + "state": "CA", + "country": "USA", + "zip": "12345" } } }, "400": { - "description": "\"list_id\" : \"Returned if list_id is not valid\"", + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid id" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } - ] + } } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, "examples": { "application/json": { "errors": [ { - "field": null, - "message": "authorization required" + "message": "one or more of given scopes are invalid", + "field": "scopes" } ] } } }, "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } }, "examples": { "application/json": { "errors": [ { - "field": null, - "message": "List ID does not exist" + "message": "username not found", + "field": "username" } ] } @@ -5352,104 +4629,68 @@ } ] }, - "patch": { - "operationId": "PATCH_contactdb-lists-list_id", - "summary": "Update a List", + "delete": { + "operationId": "DELETE_v3-teammates-username", + "summary": "Delete teammate", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to update the name of one of your recipient lists.**\n\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to delete a teammate.**\n\n**Only the parent user or an admin teammate can delete another teammate.**", "parameters": [ - { - "name": "list_id", - "in": "query", - "description": "The ID of the list you are updating.", - "required": true, - "type": "integer" - }, - { - "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" - ], - "example": { - "name": "newlistname" - } - } - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "204": { "description": "", "schema": { "type": "object", "properties": { - "id": { - "type": "integer", - "description": "The ID of the list" - }, - "name": { - "type": "string", - "description": "The new name for the list" - }, - "recipient_count": { - "type": "integer", - "description": "The number of recipients on the list" + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } } } - }, - "examples": { - "application/json": { - "id": 1234, - "name": "2016 iPhone Users", - "recipient_count": 0 - } } }, - "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\"", + "404": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid id" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } - ] + } } - } - }, - "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" + "message": "username not found", + "field": "username" } ] } @@ -5461,94 +4702,68 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_contactdb-lists-list_id", - "summary": "Delete a List", + } + }, + "/scopes/requests/{request_id}/approve": { + "parameters": [ + { + "name": "request_id", + "in": "path", + "description": "The ID of the request that you want to approve.", + "required": true, + "type": "string" + } + ], + "patch": { + "operationId": "PATCH_v3-scopes-requests-approve-id", + "summary": "Approve access request", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to delete a specific recipient list with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "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 - ] - }, - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Teammates" ], + "description": "**This endpoint allows you to approve an access attempt.**\n\n**Note:** Only teammate admins may approve another teammate’s access request.", "responses": { - "202": { + "200": { "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" + "type": "object", + "properties": { + "scope_group_name": { + "type": "string", + "description": "name of feature teammate will be given access to" + } + } }, "examples": { "application/json": { - "errors": [ - { - "field": "delete_contacts", - "message": "delete_contacts not a bool" - }, - { - "field": "list_id", - "message": "Returned if list_id is not valid" - } - ] + "scope_group_name": "Stats" } } }, "401": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + "type": "object" } }, "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"", + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "List not found: 5" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } - ] + } } } } @@ -5560,159 +4775,57 @@ ] } }, - "/contactdb/lists/{list_id}/recipients": { + "/scopes/requests/{request_id}": { "parameters": [ { - "name": "list_id", + "name": "request_id", "in": "path", - "description": "The id of the list of recipients you want to retrieve.", + "description": "The ID of the request that you want to deny.", "required": true, - "type": "integer" + "type": "string" } ], - "get": { - "operationId": "GET_contactdb-lists-list_id-recipients", - "summary": "Retrieve all recipients on a List", + "delete": { + "operationId": "DELETE_v3-scopes-requests-request_id", + "summary": "Deny access request", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to retrieve all recipients on the list with the given ID.** \n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Teammates" ], - "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" + "description": "**This endpoint allows you to deny an attempt to access your account.**\n\n**Note:** Only teammate admins may delete a teammate's access request.", + "responses": { + "204": { + "description": "" }, - { - "name": "list_id", - "in": "query", - "description": "The ID of the list whose recipients you are requesting.", - "required": true, - "type": "integer" + "401": { + "description": "" }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { + "404": { "description": "", "schema": { "type": "object", "properties": { - "recipients": { + "errors": { "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" + "type": "object", + "properties": { + "message": { + "type": "string" }, - { - "id": 6240, - "name": "lname", - "type": "text", - "value": null + "field": { + "type": "string" } - ], - "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" }, "examples": { "application/json": { "errors": [ { - "field": "list_id", - "message": "Returned if list_id is invalid" + "message": "Cannot find request", + "field": "request_id" } ] } @@ -5724,107 +4837,53 @@ "Authorization": [] } ] - }, - "post": { - "operationId": "POST_contactdb-lists-list_id-recipients", - "summary": "Add Multiple Recipients to a List", + } + }, + "/teammates/pending/{token}": { + "parameters": [ + { + "name": "token", + "in": "path", + "description": "The token for the invite you want to delete.", + "required": true, + "type": "string" + } + ], + "delete": { + "operationId": "DELETE_v3-teammates-pending-token", + "summary": "Delete pending teammate", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to add multiple recipients to a list.**\n\nAdds 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 Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Teammates" ], + "description": "**This endpoint allows you to delete a pending teammate invite.**", "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "recipient_id1", - "recipient_id2" - ] - } - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "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" - } - ] - } - } + "204": { + "description": "" }, "404": { - "description": "\"list_id\": \"Returned if list_id does not exist\"", + "description": "", "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" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } - ] + } } } } @@ -5836,105 +4895,132 @@ ] } }, - "/contactdb/lists/{list_id}/recipients/{recipient_id}": { - "parameters": [ - { - "name": "list_id", - "in": "path", - "description": "The ID of the list that you want to add the recipient to.", - "required": true, - "type": "integer" - }, - { - "name": "recipient_id", - "in": "path", - "description": "The ID of the recipient you are adding to the list.", - "required": true, - "type": "string" - } - ], + "/alerts": { "post": { - "operationId": "POST_contactdb-lists-list_id-recipients-recipient_id", - "summary": "Add a Single Recipient to a List", + "operationId": "POST_alerts", + "summary": "Create a new Alert", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to add a single recipient to a list.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Alerts" ], + "description": "**This endpoint allows you to create a new alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint:\n\n* `usage_limit` allows you to set the threshold at which an alert will be sent.\n* `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The type of alert you want to create. Can be either usage_limit or stats_notification.\nExample: usage_limit", + "enum": [ + "stats_notification", + "usage_limit" + ] + }, + "email_to": { + "type": "string", + "description": "The email address the alert will be sent to.\nExample: test@example.com", + "format": "email", + "nullable": true + }, + "frequency": { + "type": "string", + "description": "Required for stats_notification. How frequently the alert will be sent.\nExample: daily" + }, + "percentage": { + "type": "integer", + "description": "Required for usage_alert. When this usage threshold is reached, the alert will be sent.\nExample: 90" + } + }, + "required": [ + "type", + "email_to" + ], + "example": { + "type": "stats_notification", + "email_to": "example@example.com", + "frequency": "daily" + } } }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "Authorization", + "in": "header", + "type": "string" + }, + { + "name": "on-behalf-of", + "in": "header", + "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" + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was created." + }, + "email_to": { + "type": "string", + "description": "The email address that the alert will be sent to.", + "format": "email" + }, + "frequency": { + "type": "string", + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." + }, + "id": { + "type": "integer", + "description": "The ID of the alert." + }, + "type": { + "type": "string", + "description": "The type of alert." + }, + "updated_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was last modified." + }, + "percentage": { + "type": "integer", + "description": "\"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." + } + }, + "required": [ + "created_at", + "email_to", + "id", + "type", + "updated_at" + ] }, "examples": { "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id is invalid" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id is invalid" - } - ] + "created_at": 1451520930, + "email_to": "test@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451520930 } } }, - "401": { + "400": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - } - }, - "404": { - "description": "\"list_id\" : \"Returned if list_id does not exist\"\n\"recipient_id\" : \"Returned if recipient_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "list_id", - "message": "Returned if list_id does not exist" - }, - { - "field": "recipient_id", - "message": "Returned if recipient_id does not exist" - } - ] + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + } } } } @@ -5945,103 +5031,100 @@ } ] }, - "delete": { - "operationId": "DELETE_contactdb-lists-list_id-recipients-recipient_id", - "summary": "Delete a Single Recipient from a Single List", + "get": { + "operationId": "GET_alerts", + "summary": "Retrieve all alerts", "tags": [ - "Contacts API - Lists" - ], - "description": "**This endpoint allows you to delete a single recipient from a list.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Alerts" ], + "description": "**This endpoint allows you to retrieve all of your alerts.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { - "name": "list_id", - "in": "query", - "description": "The ID of the list you are taking this recipient away from.", - "required": true, - "type": "integer" - }, - { - "name": "recipient_id", - "in": "query", - "description": "The ID of the recipient to take off the list.", - "required": true, - "type": "integer" - }, - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + "name": "Authorization", + "in": "header", + "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { + "200": { "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" + "type": "array", + "description": "The list of alerts.", + "items": { + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was created." }, - { - "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" + "email_to": { + "type": "string", + "description": "The email address that the alert will be sent to." + }, + "id": { + "type": "integer", + "description": "The ID of the alert." + }, + "percentage": { + "type": "integer", + "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." + }, + "type": { + "type": "string", + "description": "The type of alert.", + "enum": [ + "usage_limit", + "stats_notification" + ] + }, + "updated_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was last modified." + }, + "frequency": { + "type": "string", + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." } + }, + "required": [ + "created_at", + "email_to", + "id", + "type" ] } - } - }, - "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" - } - ] - } + "application/json": [ + { + "created_at": 1451498784, + "email_to": "example1@example.com", + "id": 46, + "percentage": 90, + "type": "usage_limit", + "updated_at": 1451498784 + }, + { + "created_at": 1451498812, + "email_to": "example2@example.com", + "frequency": "monthly", + "id": 47, + "type": "stats_notification", + "updated_at": 1451498812 + }, + { + "created_at": 1451520930, + "email_to": "example3@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451520930 + } + ] } } }, @@ -6052,22 +5135,28 @@ ] } }, - "/contactdb/status": { + "/alerts/{alert_id}": { + "parameters": [ + { + "name": "alert_id", + "in": "path", + "description": "The ID of the alert you would like to retrieve.", + "required": true, + "type": "integer" + } + ], "get": { - "operationId": "GET_contactdb-status", - "summary": "Get Contact Upload Status", + "operationId": "GET_alerts-alert_id", + "summary": "Retrieve a specific alert", "tags": [ - "Contacts API - Recipients" - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Alerts" ], + "description": "**This endpoint allows you to retrieve a specific alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" + "name": "Authorization", + "in": "header", + "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -6079,163 +5168,83 @@ "schema": { "type": "object", "properties": { - "status": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "value": { - "type": "string" - } - } - } + "created_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was created." + }, + "email_to": { + "type": "string", + "description": "The email address that the alert will be sent to." + }, + "frequency": { + "type": "string", + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." + }, + "id": { + "type": "integer", + "description": "The ID of the alert." + }, + "type": { + "type": "string", + "description": "The type of alert.", + "enum": [ + "usage_alert", + "stats_notification" + ] + }, + "updated_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was last modified." + }, + "percentage": { + "type": "integer", + "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." } - } + }, + "required": [ + "created_at", + "email_to", + "id", + "type", + "updated_at" + ] }, "examples": { "application/json": { - "status": [ - { - "id": "worker_delay", - "value": "delayed" - }, - { - "id": "worker_delay_seconds", - "value": "75.0" - } - ] + "created_at": 1451520930, + "email_to": "example@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451520930 } } } - } - } - }, - "/contactdb/recipients": { - "post": { - "operationId": "POST_contactdb-recipients", - "summary": "Add recipients", - "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to add a Marketing Campaigns recipient.**\n\nYou 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 Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ + }, + "security": [ { - "name": "body", - "in": "body", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address of the recipient.", - "format": "email" - }, - "first_name": { - "type": "string", - "description": "The first name of the recipient." - }, - "last_name": { - "type": "string", - "description": "The last name of the recipient." - }, - "age": { - "type": "integer" - } - }, - "required": [ - "email" - ] - }, - "example": [ - { - "email": "example@example.com", - "first_name": "", - "last_name": "User", - "age": 25 - }, - { - "email": "example2@example.com", - "first_name": "Example", - "last_name": "User", - "age": 25 - } - ] - } - }, + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_alerts-alert_id", + "summary": "Delete an alert", + "tags": [ + "Alerts" + ], + "description": "**This endpoint allows you to delete an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", + "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "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": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + "type": "object", + "properties": {} } } }, @@ -6246,51 +5255,35 @@ ] }, "patch": { - "operationId": "PATCH_contactdb-recipients", - "summary": "Update Recipient", + "operationId": "PATCH_alerts-alert_id", + "summary": "Update an alert", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to update one or more recipients.**\n\nThe body of an API call to this endpoint must include an array of one or more 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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Alerts" ], + "description": "**This endpoint allows you to update an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "name": "body", "in": "body", "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." - } + "type": "object", + "properties": { + "email_to": { + "type": "string", + "description": "The new email address you want your alert to be sent to.\nExample: test@example.com" }, - "required": [ - "email" - ] - }, - "example": [ - { - "email": "jones@example.com", - "last_name": "Jones", - "first_name": "Guy" + "frequency": { + "type": "string", + "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly" + }, + "percentage": { + "type": "integer", + "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90" } - ] + }, + "example": { + "email_to": "example@example.com" + } } }, { @@ -6298,41 +5291,60 @@ } ], "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": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "created_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was created." + }, + "email_to": { + "type": "string", + "description": "The email address that the alert will be sent to." + }, + "frequency": { + "type": "string", + "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." + }, + "id": { + "type": "integer", + "description": "The ID of the alert." + }, + "type": { + "type": "string", + "description": "The type of alert.", + "enum": [ + "usage_alert", + "stats_notification" + ] + }, + "updated_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the alert was last modified." + }, + "percentage": { + "type": "integer", + "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." + } + }, + "required": [ + "created_at", + "email_to", + "id", + "type", + "updated_at" + ] }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "created_at": 1451520930, + "email_to": "example@example.com", + "frequency": "daily", + "id": 48, + "type": "stats_notification", + "updated_at": 1451522691 } } } @@ -6342,33 +5354,126 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_contactdb-recipients", - "summary": "Delete Recipient", + } + }, + "/user/profile": { + "get": { + "operationId": "GET_user-profile", + "summary": "Get a user's profile", "tags": [ - "Contacts API - Recipients" + "Users API" ], - "description": "**This endpoint allows you to deletes one or more recipients.**\n\nThe body of an API call to this endpoint must include an array of recipient IDs of the recipients you want 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).", - "consumes": [ - "application/json" + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], - "produces": [ - "application/json" + "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" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_user-profile", + "summary": "Update a user's profile", + "tags": [ + "Users API" ], + "description": "**This endpoint allows you to update your current profile details.**\n\nAny one or more of the parameters can be updated via the PATCH `/user/profile` endpoint. You must include at least one when you PATCH.", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "array", - "items": { - "type": "string" - }, - "example": [ - "recipient_id1", - "recipient_id2" - ] + "$ref": "#/definitions/user_profile", + "example": { + "first_name": "Example", + "last_name": "User", + "city": "Orange" + } } }, { @@ -6379,28 +5484,28 @@ "200": { "description": "", "schema": { - "type": "object" - } - }, - "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" + "$ref": "#/definitions/user_profile" }, "examples": { "application/json": { - "errors": [ - { - "message": "No recipient ids provided" - } - ] + "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" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { @@ -6419,30 +5524,17 @@ "Authorization": [] } ] - }, + } + }, + "/user/account": { "get": { - "operationId": "GET_contactdb-recipients", - "summary": "Retrieve recipients", + "operationId": "GET_user-account", + "summary": "Get a user's account information.", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.**\n\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\nthe list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Users API" ], + "description": "**This endpoint allows you to retrieve your user account details.**\n\nYour user's account information includes the user's account type and reputation.", "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" - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -6451,40 +5543,31 @@ "200": { "description": "", "schema": { - "title": "List Recipients response", + "title": "GET User Account response", "type": "object", "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object" - } + "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": [ - "recipients" + "type", + "reputation" ] - } - }, - "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\"", - "schema": { - "type": "object" - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "reputation": 100, + "type": "paid" } } } @@ -6496,26 +5579,14 @@ ] } }, - "/contactdb/recipients/{recipient_id}": { - "parameters": [ - { - "name": "recipient_id", - "in": "path", - "description": "The ID of the recipient that you want to retrieve.", - "required": true, - "type": "string" - } - ], + "/user/email": { "get": { - "operationId": "GET_contactdb-recipients-recipient_id", - "summary": "Retrieve a single recipient", + "operationId": "GET_user-email", + "summary": "Retrieve your account email address", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to retrieve a single recipient by ID from your contact database.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Users API" ], + "description": "**This endpoint allows you to retrieve the email address currently on file for your account.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -6525,36 +5596,23 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/contactdb_recipient" - } - }, - "400": { - "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", - "schema": { - "type": "object" - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address currently on file for your account.", + "format": "email" + } + }, + "required": [ + "email" + ] }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "email": "test@example.com" } } - }, - "404": { - "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"", - "schema": { - "type": "object" - } } }, "security": [ @@ -6563,22 +5621,28 @@ } ] }, - "delete": { - "operationId": "DELETE_contactdb-recipients-recipient_id", - "summary": "Delete a Recipient", + "put": { + "operationId": "PUT_user-email", + "summary": "Update your account email address", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to delete a single recipient with the given ID from your contact database.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Users API" ], + "description": "**This endpoint allows you to update the email address currently on file for your account.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The new email address that you would like to use for your account." + } + }, + "example": { + "email": "example@example.com" + } } }, { @@ -6586,57 +5650,24 @@ } ], "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - }, - "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": { + "200": { "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" + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The current email address on file for your account.", + "format": "email" + } + }, + "required": [ + "email" + ] }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "recipient_id is not valid" - } - ] + "email": "example@example.com" } } } @@ -6648,26 +5679,14 @@ ] } }, - "/contactdb/recipients/{recipient_id}/lists": { - "parameters": [ - { - "name": "recipient_id", - "in": "path", - "description": "The ID of the recipient for whom you are retrieving lists.", - "required": true, - "type": "string" - } - ], + "/user/username": { "get": { - "operationId": "GET_contactdb-recipients-recipient_id-lists", - "summary": "Retrieve the lists that a recipient is on", + "operationId": "GET_user-username", + "summary": "Retrieve your username", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to retrieve the lists that a given recipient belongs to.**\n\nEach recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Users API" ], + "description": "**This endpoint allows you to retrieve your current account username.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -6679,71 +5698,24 @@ "schema": { "type": "object", "properties": { - "lists": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_list" - } + "username": { + "type": "string", + "description": "Your account username." + }, + "user_id": { + "type": "integer", + "description": "The user ID for your account." } - } - }, - "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" + }, + "required": [ + "username", + "user_id" + ] }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "recipient id not found" - } - ] + "username": "test_username", + "user_id": 1 } } } @@ -6753,20 +5725,31 @@ "Authorization": [] } ] - } - }, - "/contactdb/recipients/billable_count": { - "get": { - "operationId": "GET_contactdb-recipients-billable_count", - "summary": "Retrieve the count of billable recipients", + }, + "put": { + "operationId": "PUT_user-username", + "summary": "Update your username", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**\n\nYou are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", - "produces": [ - "application/json" + "Users API" ], + "description": "**This endpoint allows you to update the username for your account.**", "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The new username you would like to use for your account." + } + }, + "example": { + "username": "test_username" + } + } + }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -6775,27 +5758,20 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/contactdb_recipient_count" - }, - "examples": { - "application/json": { - "recipient_count": 1234 - } - } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The current username on file for your account." + } + }, + "required": [ + "username" + ] }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] + "username": "test_username" } } } @@ -6807,17 +5783,14 @@ ] } }, - "/contactdb/recipients/count": { + "/user/credits": { "get": { - "operationId": "GET_contactdb-recipients-count", - "summary": "Retrieve a Count of Recipients", + "operationId": "GET_user-credits", + "summary": "Retrieve your credit balance", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "produces": [ - "application/json" + "Users API" ], + "description": "**This endpoint allows you to retrieve the current credit balance for your account.**\n\nEach account has a credit balance, which is a base number of emails it can send before receiving per-email charges. For more information about credits and billing, see [Billing and Plan details information](https://sendgrid.com/docs/ui/account-and-settings/billing/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -6827,29 +5800,58 @@ "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" - } - ] - } - } + "type": "object", + "properties": { + "remain": { + "type": "integer", + "description": "The remaining number of credits available on your account." + }, + "total": { + "type": "integer", + "description": "The total number of credits assigned to your account." + }, + "overage": { + "type": "integer", + "description": "The number of overdrawn credits for your account." + }, + "used": { + "type": "integer", + "description": "The number of credits that you have used." + }, + "last_reset": { + "type": "string", + "description": "The date that your credit balance was last reset." + }, + "next_reset": { + "type": "string", + "description": "The next date that your credit balance will be reset." + }, + "reset_frequency": { + "type": "string", + "description": "The frequency at which your credit balance will be reset." + } + }, + "required": [ + "remain", + "total", + "overage", + "used", + "last_reset", + "next_reset", + "reset_frequency" + ] + }, + "examples": { + "application/json": { + "remain": 200, + "total": 200, + "overage": 0, + "used": 0, + "last_reset": "2013-01-01", + "next_reset": "2013-02-01", + "reset_frequency": "monthly" + } + } } }, "security": [ @@ -6859,22 +5861,39 @@ ] } }, - "/contactdb/recipients/search": { - "get": { - "operationId": "GET_contactdb-recipients-search", - "summary": "Retrieve recipients matching search criteria", + "/user/password": { + "put": { + "operationId": "PUT_user-password", + "summary": "Update your password", "tags": [ - "Contacts API - Recipients" - ], - "description": "**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.**\n\nfield_name:\n\n* is a variable that is substituted for your actual custom field name from your recipient.\n* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)\n* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert\nyour epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to\nMon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through\nMon, 02 Feb 2015 23:59:59 GMT.\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", - "produces": [ - "application/json" + "Users API" ], + "description": "**This endpoint allows you to update your password.**", "parameters": [ { - "name": "{field_name}", - "in": "query", - "type": "string" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "new_password": { + "type": "string", + "description": "The new password you would like to use for your account." + }, + "old_password": { + "type": "string", + "description": "The old password for your account." + } + }, + "required": [ + "new_password", + "old_password" + ], + "example": { + "new_password": "new_password", + "old_password": "old_password" + } + } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -6885,63 +5904,75 @@ "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" - } - ] - } - ] - } + "properties": {} } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/subusers": { + "get": { + "operationId": "GET_subusers", + "summary": "List all Subusers", + "tags": [ + "Subusers API" + ], + "description": "**This endpoint allows you to retrieve a list of all of your subusers.**\n\nYou can choose to retrieve specific subusers as well as limit the results that come back from the API.", + "parameters": [ + { + "name": "username", + "in": "query", + "description": "The username of this subuser.", + "type": "string" }, - "400": { - "description": "\"\" : \"Returned if no search params are specified\"\n\"field\" : \"Returned if the provided field is invalid or does not exist\"", + { + "name": "limit", + "in": "query", + "description": "The number of results you would like to get in each request.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "The number of subusers to skip.", + "type": "integer" + } + ], + "responses": { + "200": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "array", + "items": { + "$ref": "#/definitions/subuser" + } }, "examples": { - "application/json": { - "errors": [ - { - "message": "The following parameters are not custom fields or reserved fields: [{field_name}]" - }, - { - "message": "No search params are specified" - } - ] - } + "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": "", + "description": "Unexpected error in API call. See HTTP response body for details.", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { @@ -6960,142 +5991,93 @@ "Authorization": [] } ] - } - }, - "/contactdb/segments": { + }, "post": { - "operationId": "POST_contactdb-segments", - "summary": "Create a Segment", + "operationId": "POST_subusers", + "summary": "Create Subuser", "tags": [ - "Contacts API - Segments" - ], - "description": "**This endpoint allows you to create a segment.**\n\nAll 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 Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Subusers API" ], + "description": "**This endpoint allows you to create a new subuser.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/contactdb_segments", - "example": { - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - }, - { - "field": "last_clicked", - "value": "01/02/2015", - "operator": "gt", - "and_or": "and" - }, - { - "field": "clicks.campaign_identifier", - "value": "513", - "operator": "eq", - "and_or": "or" + "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" } - ] - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + }, + "required": [ + "username", + "email", + "password", + "ips" + ], + "example": { + "username": "John@example.com", + "email": "John@example.com", + "password": "johns_password", + "ips": [ + "1.1.1.1", + "2.2.2.2" + ] + } + } } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/contactdb_segments_with_id" + "$ref": "#/definitions/subuser_post" }, "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 + "username": "example_subuser", + "user_id": 1234, + "email": "example@example.com", + "signup_session_token": "", + "authorization_token": "", + "credit_allocation": { + "type": "unlimited" + } } } }, "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\"", + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "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" + "message": "username exists" }, { - "field": "name", - "message": "the name is not valid" + "message": "unable to validate IPs at this time" } ] } @@ -7104,7 +6086,7 @@ "401": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { @@ -7116,89 +6098,32 @@ ] } } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "operationId": "GET_contactdb-segments", - "summary": "Retrieve all segments", - "tags": [ - "Contacts API - Segments" - ], - "description": "**This endpoint allows you to retrieve all of your segments.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { + }, + "403": { "description": "", "schema": { - "title": "List All Segments response", - "type": "object", - "properties": { - "segments": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_segments" - } - } - }, - "required": [ - "segments" - ] + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { - "segments": [ - { - "id": 1234, - "name": "Age segments < 25", - "conditions": [ - { - "field": "age", - "value": "25", - "operator": "lt" - } - ], - "recipient_count": 8 - }, + "errors": [ { - "id": 2345, - "name": "email address - gmail", - "conditions": [ - { - "field": "email", - "value": "@gmail.com", - "operator": "contains" - } - ], - "recipient_count": 0 + "message": "you dont have permission to access this resource" } ] } } }, - "401": { + "500": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "type": "object" }, "examples": { "application/json": { "errors": [ { - "field": null, - "message": "authorization required" + "message": "unable to validate IPs at this time" } ] } @@ -7212,70 +6137,61 @@ ] } }, - "/contactdb/segments/{segment_id}": { + "/subusers/{subuser_name}": { "parameters": [ { - "name": "segment_id", + "name": "subuser_name", "in": "path", "required": true, "type": "string" } ], - "get": { - "operationId": "GET_contactdb-segments-segment_id", - "summary": "Retrieve a segment", + "patch": { + "operationId": "PATCH_subusers-subuser_name", + "summary": "Enable/disable a subuser", "tags": [ - "Contacts API - Segments" - ], - "description": "**This endpoint allows you to retrieve a single segment with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", - "produces": [ - "application/json" + "Subusers API" ], + "description": "**This endpoint allows you to enable or disable a subuser.**", "parameters": [ { - "name": "segment_id", - "in": "query", - "description": "The ID of the segment you want to request.", - "required": true, - "type": "integer" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "disabled": { + "type": "boolean", + "description": "Whether or not this subuser is disabled. True means disabled, False means enabled." + } + }, + "example": { + "disabled": false + } + } } ], "responses": { - "200": { + "204": { "description": "", "schema": { - "$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 - } + "type": "object", + "properties": {} } }, "400": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"", + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { - "message": "if segment_id is not valid" + "message": "invalid username" + }, + { + "message": "no fields provided" } ] } @@ -7284,7 +6200,7 @@ "401": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { @@ -7297,16 +6213,16 @@ } } }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", + "500": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { - "message": "segment_id not found" + "message": "unable to enable user" } ] } @@ -7319,163 +6235,94 @@ } ] }, - "patch": { - "operationId": "PATCH_contactdb-segments-segment_id", - "summary": "Update a segment", + "delete": { + "operationId": "DELETE_subusers-subuser_name", + "summary": "Delete a subuser", "tags": [ - "Contacts API - Segments" - ], - "description": "**This endpoint allows you to update a segment.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", - "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" - ], - "example": { - "name": "The Millers", - "list_id": 5, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ] - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Subusers API" ], + "description": "**This endpoint allows you to delete a subuser.**\n\nThis is a permanent action. Once deleted, a subuser cannot be retrieved.", "responses": { - "200": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/contactdb_segments" - }, - "examples": { - "application/json": { - "id": 5, - "name": "The Millers", - "list_id": 5, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - } - ], - "recipient_count": 1 - } + "type": "object", + "properties": {} } }, - "400": { + "401": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "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" + "field": null, + "message": "authorization required" } ] } } - }, - "401": { + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/subusers/reputations": { + "get": { + "operationId": "GET_subusers-reputations", + "summary": "Retrieve Subuser Reputations", + "tags": [ + "Subusers API" + ], + "description": "**This endpoint allows you to request the reputations for your subusers.**\n\nSubuser 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 affect your sender rating.", + "parameters": [ + { + "name": "usernames", + "in": "query", + "type": "string" + } + ], + "responses": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "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 + } + ] } } }, @@ -7484,58 +6331,61 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_contactdb-segments-segment_id", - "summary": "Delete a segment", + } + }, + "/subusers/{subuser_name}/ips": { + "parameters": [ + { + "name": "subuser_name", + "in": "path", + "required": true, + "type": "string" + } + ], + "put": { + "operationId": "PUT_subusers-subuser_name-ips", + "summary": "Update IPs assigned to a subuser", "tags": [ - "Contacts API - Segments" - ], - "description": "**This endpoint allows you to delete a segment from your recipients database.**\n\nYou also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", - "produces": [ - "application/json" + "Subusers API" ], + "description": "**This endpoint allows you update your subusers' assigned IP.**\n\nEach 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 one or more of their own IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/)\n* [Setup Reverse DNS](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/)", "parameters": [ - { - "name": "delete_contacts", - "in": "query", - "description": "True to delete all contacts matching the segment in addition to deleting the segment", - "type": "boolean" - }, { "name": "body", "in": "body", "schema": { - "type": "null" + "type": "array", + "description": "The IP addresses you would like to assign to the subuser.", + "items": { + "type": "string", + "format": "ipv4" + }, + "example": [ + "127.0.0.1" + ] } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { + "200": { "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" + "type": "object", + "properties": { + "ips": { + "type": "array", + "description": "The IP addresses that are assigned to the subuser.", + "items": { + "type": "string", + "format": "ipv4" + } + } + } }, "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" - } + "ips": [ + "127.0.0.1" ] } } @@ -7543,7 +6393,7 @@ "401": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { @@ -7555,22 +6405,6 @@ ] } } - }, - "404": { - "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "segment_id", - "message": "segment_id does not exist" - } - ] - } - } } }, "security": [ @@ -7580,95 +6414,39 @@ ] } }, - "/contactdb/segments/{segment_id}/recipients": { + "/subusers/{subuser_name}/monitor": { "parameters": [ { - "name": "segment_id", + "name": "subuser_name", "in": "path", - "description": "The ID of the segment from which you want to retrieve recipients.", + "description": "The name of the subuser for which to retrieve monitor settings.", "required": true, - "type": "integer" + "type": "string" } ], "get": { - "operationId": "GET_contactdb-segments-segment_id-recipients", - "summary": "Retrieve recipients on a segment", + "operationId": "GET_subusers-subuser_name-monitor", + "summary": "Retrieve monitor settings for a subuser", "tags": [ - "Contacts API - Segments" - ], - "description": "**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.\n\nFor more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "page", - "in": "query", - "type": "integer" - }, - { - "name": "page_size", - "in": "query", - "type": "integer" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Subuser Monitor Settings" ], "responses": { "200": { "description": "", "schema": { - "title": "List Recipients On a Segment response", - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "$ref": "#/definitions/contactdb_recipient" - } - } - }, - "required": [ - "recipients" - ] + "$ref": "#/definitions/monitor" }, "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" - } - ] - } - ] + "email": "example@example.com", + "frequency": 500 } } }, - "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\"", - "schema": { - "type": "object" - } - }, "401": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { @@ -7682,9 +6460,19 @@ } }, "404": { - "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"", + "description": "", "schema": { - "type": "object" + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "No monitor settings for this user" + } + ] + } } } }, @@ -7693,90 +6481,69 @@ "Authorization": [] } ] - } - }, - "/suppression/invalid_emails": { - "get": { - "operationId": "GET_suppression-invalid_emails", - "summary": "Retrieve all invalid emails", + }, + "post": { + "operationId": "POST_subusers-subuser_name-monitor", + "summary": "Create monitor settings", "tags": [ - "Invalid Emails API" - ], - "description": "**This endpoint allows you to retrieve a list of all invalid email addresses.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server.\n\nExamples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", - "produces": [ - "application/json" + "Subuser Monitor Settings" ], "parameters": [ { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when an invalid email was created (inclusive).", - "type": "integer" - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when an invalid email was created (inclusive).", - "type": "integer" - }, - { - "name": "limit", - "in": "query", - "description": "Limit the number of results to be displayed per page.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset. The point in the list to begin displaying results.", - "type": "integer" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/monitor", + "example": { + "email": "example@example.com", + "frequency": 50000 + } + } } ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "description": "The list of invalid email addresses.", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the email address was added to the invalid emails list." - }, - "email": { - "type": "string", - "description": "The email address that was marked as invalid." - }, - "reason": { - "type": "string", - "description": "The reason that the email address was marked as invalid." + "$ref": "#/definitions/monitor" + }, + "examples": { + "application/json": { + "email": "example@example.com", + "frequency": 50000 + } + } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "User already has a monitor" } - }, - "required": [ - "created", - "email", - "reason" ] } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" }, "examples": { - "application/json": [ - { - "created": 1449953655, - "email": "user1@example.com", - "reason": "Mail domain mentioned in email address is unknown" - }, - { - "created": 1449939373, - "email": "user1@example.com", - "reason": "Mail domain mentioned in email address is unknown" - } - ] + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } } } }, @@ -7786,153 +6553,82 @@ } ] }, - "delete": { - "operationId": "DELETE_suppression-invalid_emails", - "summary": "Delete invalid emails", + "put": { + "operationId": "PUT_subusers-subuser_name-monitor", + "summary": "Update Monitor Settings for a subuser", "tags": [ - "Invalid Emails API" - ], - "description": "**This endpoint allows you to remove email addresses from your invalid email address list.**\n\nThere are two options for deleting invalid email addresses: \n\n1) You can delete all invalid email addresses by setting `delete_all` to true in the request body.\n2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body.\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server.\n\nExamples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", - "produces": [ - "application/json" + "Subuser Monitor Settings" ], "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "object", - "properties": { - "delete_all": { - "type": "boolean", - "description": "Indicates if you want to remove all email address from the invalid emails list." - }, - "emails": { - "type": "array", - "description": "The list of specific email addresses that you want to remove.", - "items": { - "type": "string" - } - } - }, + "$ref": "#/definitions/monitor", "example": { - "delete_all": false, - "emails": [ - "example1@example.com", - "example2@example.com" - ] + "email": "example@example.com", + "frequency": 500 } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "object", - "properties": {} + "$ref": "#/definitions/monitor" + }, + "examples": { + "application/json": { + "email": "example@example.com", + "frequency": 500 + } } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/suppression/invalid_emails/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The specific email address of the invalid email entry that you want to retrieve.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_suppression-invalid_emails-email", - "summary": "Retrieve a specific invalid email", - "tags": [ - "Invalid Emails API" - ], - "description": "**This endpoint allows you to retrieve a specific invalid email addresses.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server.\n\nExamples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { + "400": { "description": "", "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the email address was added to the invalid emails list." - }, - "email": { - "type": "string", - "description": "The email address that was marked as invalid." - }, - "reason": { - "type": "string", - "description": "A reason explaining why the email address was marked as invalid." + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "email", + "message": "Email is required" } - }, - "required": [ - "created", - "email", - "reason" ] } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" }, "examples": { - "application/json": [ - { - "created": 1454433146, - "email": "test1@example.com", - "reason": "Mail domain mentioned in email address is unknown" - } - ] + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } } } - } + }, + "security": [ + { + "Authorization": [] + } + ] }, "delete": { - "operationId": "DELETE_suppression-invalid_emails-email", - "summary": "Delete a specific invalid email", + "operationId": "DELETE_subusers-subuser_name-monitor", + "summary": "Delete monitor settings", "tags": [ - "Invalid Emails API" - ], - "description": "**This endpoint allows you to remove a specific email address from the invalid email address list.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server.\n\nExamples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Subuser Monitor Settings" ], "responses": { "204": { @@ -7941,77 +6637,141 @@ "type": "object", "properties": {} } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "No monitor settings for this user" + } + ] + } + } } - } + }, + "security": [ + { + "Authorization": [] + } + ] } }, - "/access_settings/activity": { + "/subusers/{subuser_name}/stats/monthly": { + "parameters": [ + { + "name": "subuser_name", + "in": "path", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_access_settings-activity", - "summary": "Retrieve all recent access attempts", + "operationId": "GET_subusers-subuser_name-stats-monthly", + "summary": "Retrieve the monthly email statistics for a single subuser", "tags": [ - "IP Access Management" - ], - "description": "**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", - "produces": [ - "application/json" + "Subuser Statistics" ], + "description": "**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.", "parameters": [ + { + "name": "date", + "in": "query", + "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", + "required": true, + "type": "string" + }, + { + "name": "sort_by_metric", + "in": "query", + "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", + "required": false, + "type": "string", + "default": "delivered" + }, + { + "name": "sort_by_direction", + "in": "query", + "description": "The direction you want to sort.", + "required": false, + "type": "string", + "default": "desc", + "enum": [ + "desc", + "asc" + ] + }, { "name": "limit", "in": "query", - "description": "Limits the number of IPs to return.", + "description": "Optional field to limit the number of results returned.", + "required": false, "type": "integer", - "default": 20 + "default": 5 }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "offset", + "in": "query", + "description": "Optional beginning point in the list to retrieve from.", + "required": false, + "type": "integer", + "default": 0 } ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "allowed": { - "type": "boolean" - }, - "auth_method": { - "type": "string" - }, - "first_at": { - "type": "integer" - }, - "ip": { - "type": "string" - }, - "last_at": { - "type": "integer" - }, - "location": { - "type": "string" - } - } - } - } - } + "$ref": "#/definitions/subuser_stats" }, "examples": { "application/json": { - "result": [ + "date": "2016-02-01", + "stats": [ { - "allowed": false, - "auth_method": "basic", - "first_at": 1444087966, - "ip": "1.1.1.1", - "last_at": 1444406672, - "location": "Australia" + "first_name": "John", + "last_name": "Doe", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 5, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 10, + "processed": 10, + "requests": 10, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "user1", + "type": "subuser" } ] } @@ -8025,84 +6785,134 @@ ] } }, - "/access_settings/whitelist": { + "/subusers/stats/monthly": { "get": { - "operationId": "GET_access_settings-whitelist", - "summary": "Retrieve a list of currently whitelisted IPs", + "operationId": "GET_subusers-stats-monthly", + "summary": "Retrieve monthly stats for all subusers", "tags": [ - "IP Access Management" - ], - "description": "**This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.**\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", - "produces": [ - "application/json" + "Subuser Statistics" ], + "description": "**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "An array listing all of your whitelisted IPs.", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the whitelisted IP." - }, - "ip": { - "type": "string", - "description": "The whitelisted IP." - }, - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP was whitelisted." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated." - } - }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ] - } - } - }, - "required": [ - "result" - ] + "name": "date", + "in": "query", + "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", + "required": true, + "type": "string" + }, + { + "name": "subuser", + "in": "query", + "description": "A substring search of your subusers.", + "required": false, + "type": "string" + }, + { + "name": "sort_by_metric", + "in": "query", + "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", + "required": false, + "type": "string", + "default": "delivered", + "enum": [ + "blocks", + "bounces", + "clicks", + "delivered", + "opens", + "requests", + "unique_clicks", + "unique_opens", + "unsubscribes" + ] + }, + { + "name": "sort_by_direction", + "in": "query", + "description": "The direction you want to sort.", + "required": false, + "type": "string", + "default": "desc", + "enum": [ + "desc", + "asc" + ] + }, + { + "name": "limit", + "in": "query", + "description": "Optional field to limit the number of results returned.", + "required": false, + "type": "integer", + "default": 5 + }, + { + "name": "offset", + "in": "query", + "description": "Optional beginning point in the list to retrieve from.", + "required": false, + "type": "integer", + "default": 0 + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/subuser_stats" }, "examples": { "application/json": { - "result": [ - { - "id": 1, - "ip": "192.168.1.1/32", - "created_at": 1441824715, - "updated_at": 1441824715 - }, + "date": "2016-02-01", + "stats": [ { - "id": 2, - "ip": "192.168.1.2/32", - "created_at": 1441824715, - "updated_at": 1441824715 + "first_name": "John", + "last_name": "Doe", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 1, + "processed": 0, + "requests": 100, + "spam_report_drops": 0, + "spam_reports": 99, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "user1", + "type": "subuser" }, { - "id": 3, - "ip": "192.168.1.3/32", - "created_at": 1441824715, - "updated_at": 1441824715 + "first_name": "Jane", + "last_name": "Doe", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 5, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 10, + "processed": 10, + "requests": 10, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "user2", + "type": "subuser" } ] } @@ -8114,130 +6924,85 @@ "Authorization": [] } ] - }, - "post": { - "operationId": "POST_access_settings-whitelist", - "summary": "Add one or more IPs to the whitelist", + } + }, + "/subusers/stats/sums": { + "get": { + "operationId": "GET_subusers-stats-sums", + "summary": "Retrieve the totals for each email statistic metric for all subusers.", "tags": [ - "IP Access Management" - ], - "description": "**This endpoint allows you to add one or more IP addresses to your IP whitelist.**\n\nWhen adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Subuser Statistics" ], + "description": "**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ips": { - "type": "array", - "description": "An array containing the IP(s) you want to whitelist.", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "An IP address that you want to whitelist." - } - }, - "required": [ - "ip" - ] - } - } - }, - "required": [ - "ips" - ], - "example": { - "ips": [ - { - "ip": "192.168.1.1" - }, - { - "ip": "192.*.*.*" - }, - { - "ip": "192.168.1.3/32" - } - ] - } - } + "name": "sort_by_direction", + "in": "query", + "description": "The direction you want to sort. ", + "required": false, + "type": "string", + "default": "desc", + "enum": [ + "desc", + "asc" + ] }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "start_date", + "in": "query", + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "required": true, + "type": "string" + }, + { + "name": "end_date", + "in": "query", + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "required": false, + "type": "string" + }, + { + "name": "limit", + "in": "query", + "description": "Limits the number of results returned per page.", + "required": false, + "type": "integer", + "default": 5 + }, + { + "name": "offset", + "in": "query", + "description": "The point in the list to begin retrieving results from.", + "required": false, + "type": "integer", + "default": 0 + }, + { + "name": "aggregated_by", + "in": "query", + "description": "How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.", + "required": false, + "type": "string" + }, + { + "name": "sort_by_metric", + "in": "query", + "description": "The metric that you want to sort by. Must be a single metric.", + "required": false, + "type": "string", + "default": "delivered" } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "An array listing all of your whitelisted IPs.", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the whitelisted IP." - }, - "ip": { - "type": "string", - "description": "The whitelisted IP." - }, - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP was whitelisted." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated." - } - }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ] - } - } - }, - "required": [ - "result" - ] + "$ref": "#/definitions/category_stats" }, "examples": { "application/json": { - "result": [ - { - "id": 1, - "ip": "192.168.1.1/32", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 2, - "ip": "192.0.0.0/8", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 3, - "ip": "192.168.1.3/32", - "created_at": 1441824715, - "updated_at": 1441824715 - } - ] + "date": "2015-10-11", + "stats": [] } } } @@ -8247,123 +7012,344 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_access_settings-whitelist", - "summary": "Remove one or more IPs from the whitelist", + } + }, + "/subusers/stats": { + "get": { + "operationId": "GET_subusers-stats", + "summary": "Retrieve email statistics for your subusers.", "tags": [ - "IP Access Management" - ], - "description": "**This endpoint allows you to remove one or more IPs from your IP whitelist.**\n\nYou can remove one IP at a time, or you can remove multiple IP addresses.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", - "produces": [ - "application/json" + "Subuser Statistics" ], + "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.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "ids": { - "type": "array", - "description": "An array of the IDs of the IP address that you want to remove from your whitelist.", - "items": { - "type": "integer" - } - } - }, - "example": { - "ids": [ - 1, - 2, - 3 - ] - } - } + "name": "limit", + "in": "query", + "description": "Limits the number of results returned per page.", + "required": false, + "type": "integer" }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object", - "properties": {} - } - } - }, - "security": [ + "name": "offset", + "in": "query", + "description": "The point in the list to begin retrieving results from.", + "required": false, + "type": "integer" + }, { - "Authorization": [] - } - ] - } - }, - "/access_settings/whitelist/{rule_id}": { - "parameters": [ - { - "name": "rule_id", - "in": "path", - "description": "The ID of the whitelisted IP address that you want to retrieve.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_access_settings-whitelist-rule_id", - "summary": "Retrieve a specific whitelisted IP", - "tags": [ - "IP Access Management" - ], - "description": "**This endpoint allows you to retreive a specific IP address that has been whitelisted.**\n\nYou must include the ID for the specific IP address you want to retrieve in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", - "produces": [ - "application/json" - ], - "parameters": [ + "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" + ] + }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "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": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the IP address." + "$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 + } + } + ] }, - "ip": { - "type": "string", - "description": "The IP address." + { + "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 + } + } + ] }, - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP was whitelisted." + { + "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 + } + } + ] }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP address was last updated." - } - }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" + { + "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 + } + } + ] + } ] - }, - "examples": { - "application/json": { - "id": 1, - "ip": "192.168.1.1", - "created_at": 1441824715, - "updated_at": 1441824715 - } } } }, @@ -8372,20 +7358,48 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_access_settings-whitelist-rule_id", - "summary": "Remove a specific IP from the whitelist", + } + }, + "/whitelabel/links": { + "post": { + "operationId": "POST_whitelabel-links", + "summary": "Create a branded link", "tags": [ - "IP Access Management" + "Link branding" ], - "description": "**This endpoint allows you to remove a specific IP address from your IP whitelist.**\n\nWhen removing a specific IP address from your whitelist, you must include the ID in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", + "description": "**This endpoint allows you to create a new branded link.**\n\nTo create the link branding, supply the root domain and, optionally, the subdomain — these go into separate fields in your request body. The root domain should match your FROM email address. If you provide a subdomain, it must be different from the subdomain you used for authenticating your domain.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": "The root domain for the subdomain that you are creating the link branding for. This should match your FROM email address." + }, + "subdomain": { + "type": "string", + "description": "The subdomain to create the link branding for. Must be different from the subdomain you used for authenticating your domain." + }, + "default": { + "type": "boolean", + "description": "Indicates if you want to use this link branding as the default or fallback. When setting a new default, the existing default link branding will have its default status removed automatically.", + "enum": [ + true, + false + ] + } + }, + "required": [ + "domain" + ], + "example": { + "domain": "example.com", + "subdomain": "mail", + "default": true + } } }, { @@ -8393,155 +7407,35 @@ } ], "responses": { - "204": { + "201": { "description": "", "schema": { - "type": "object", - "properties": {} - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips": { - "post": { - "operationId": "POST_ips", - "summary": "Add IPs", - "tags": [ - "IP Addresses" - ], - "description": "This endpoint is for adding a(n) IP Address(es) to your account.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "count": { - "type": "integer", - "description": "The amount of IPs to add to the account." - }, - "subusers": { - "type": "array", - "description": "Array of usernames to be assigned a send IP.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "default": false, - "description": "Whether or not to warmup the IPs being added." - } - }, - "required": [ - "count" - ], - "example": { - "count": 90323478, - "subusers": [ - "subuser1", - "subuser2" - ], - "warmup": true, - "user_can_send": true - } - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "ips": { - "type": "array", - "description": "List of IP objects.", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "IP added to account." - }, - "subusers": { - "type": "array", - "description": "Array of usernames assigned a send IP.", - "items": { - "type": "string" - } - } - }, - "required": [ - "ip", - "subusers" - ] - } - }, - "remaining_ips": { - "type": "integer", - "description": "The number of IPs that can still be added to the user." - }, - "warmup": { - "type": "boolean", - "description": "Whether or not the IPs are being warmed up." - } - }, - "required": [ - "ips", - "remaining_ips", - "warmup" - ] + "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { - "ips": [ - { - "ip": "1.2.3.4", - "subusers": [ - "user", - "subuser1" - ] + "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" }, - { - "ip": "1.2.3.5", - "subusers": [ - "user", - "subuser1" - ] - } - ], - "remaining_ips": 1, - "warmup": true - } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/errors" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "one or more subusers do not belong to this user" + "owner_cname": { + "valid": true, + "type": "cname", + "host": "7.example.com", + "data": "sendgrid.net" } - ] + } } } } @@ -8553,57 +7447,21 @@ ] }, "get": { - "operationId": "GET_ips", - "summary": "Retrieve all IP addresses", + "operationId": "GET_whitelabel-links", + "summary": "Retrieve all branded links", "tags": [ - "IP Addresses" - ], - "description": "**This endpoint allows you to retrieve a list of all assigned and unassigned IPs.**\n\nResponse includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "produces": [ - "application/json" + "Link branding" ], + "description": "**This endpoint allows you to retrieve all branded links**.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "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": "limit", "in": "query", - "description": "The number of IPs you want returned at the same time.", - "type": "integer", - "default": 10 - }, - { - "name": "offset", - "in": "query", - "description": "The offset for the number of IPs that you are requesting.", - "type": "integer", - "default": 0 - }, - { - "name": "subuser", - "in": "query", - "description": "The subuser you are requesting for.", - "type": "string" + "description": "Limits the number of results returned per page.", + "type": "integer" }, { - "name": "sort_by_direction", - "in": "query", - "description": "The direction to sort the results.", - "type": "string", - "enum": [ - "desc", - "asc" - ] + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { @@ -8612,89 +7470,58 @@ "schema": { "type": "array", "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "An IP address." - }, - "subusers": { - "type": "array", - "description": "The subusers that are able to send email from this IP.", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for this IP address." - }, - "pools": { - "type": "array", - "description": "The IP pools that this IP has been added to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "type": [ - "number", - "null" - ], - "description": "The date that the IP address was entered into warmup." - }, - "whitelabeled": { - "type": "boolean", - "description": "Indicates if this IP address has been whitelabeled." - }, - "assigned_at": { - "type": [ - "integer", - "null" - ], - "description": "The date that the IP address was assigned to the user." - } - }, - "required": [ - "ip", - "subusers", - "pools", - "warmup", - "start_date", - "whitelabeled", - "assigned_at" - ] + "$ref": "#/definitions/link_branding_200_response" } }, "examples": { "application/json": [ { - "ip": "192.168.1.1", - "pools": [ - "pool1", - "pool2" - ], - "whitelabeled": false, - "start_date": 1409616000, - "subusers": [ - "tim@sendgrid.net" - ], - "warmup": false, - "assigned_at": 1482883200 - }, - { - "ip": "208.115.214.22", - "pools": [], - "whitelabeled": true, - "rdns": "o1.email.burgermail.com", - "start_date": 1409616000, - "subusers": [], - "warmup": false, - "assigned_at": 1482883200 + "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" + } + } } ] } @@ -8707,16 +7534,27 @@ ] } }, - "/ips/remaining": { - "get": { - "operationId": "GET_ips-remaining", - "summary": "Get remaining IPs count", + "/whitelabel/links/{id}/validate": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The ID of the branded link that you want to validate.", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_whitelabel-links-id-validate", + "summary": "Validate a branded link", "tags": [ - "IP Addresses" + "Link branding" ], - "description": "This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs.", - "produces": [ - "application/json" + "description": "**This endpoint allows you to validate a branded link.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "responses": { "200": { @@ -8724,43 +7562,128 @@ "schema": { "type": "object", "properties": { - "results": { + "id": { + "type": "integer", + "description": "The ID of the branded link." + }, + "valid": { + "type": "boolean", + "description": "Indicates if the link branding is valid.", + "enum": [ + true, + false + ] + }, + "validation_results": { + "type": "object", + "description": "The individual validation results for each of the DNS records associated with this branded link.", + "required": [ + "domain_cname" + ], + "properties": { + "domain_cname": { + "type": "object", + "description": "The DNS record generated for the sending domain used for this branded link.", + "required": [ + "valid", + "reason" + ], + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if this DNS record is valid.", + "enum": [ + true, + false + ] + }, + "reason": { + "type": "string", + "nullable": true, + "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 branded link.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the DNS record is valid.", + "enum": [ + true, + false + ] + }, + "reason": { + "type": "string", + "nullable": true, + "description": "Null if valid. If the DNS record is invalid, this will explain why." + } + }, + "required": [ + "valid", + "reason" + ] + } + } + } + }, + "required": [ + "id", + "valid", + "validation_results" + ] + }, + "examples": { + "application/json": { + "id": 1, + "valid": true, + "validation_results": { + "domain_cname": { + "valid": false, + "reason": "Expected CNAME to match \"sendgrid.net.\" but found \"example.com.\"." + }, + "owner_cname": { + "valid": true, + "reason": null + } + } + } + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { "type": "array", + "description": "The reasons why the validation failed.", "items": { "type": "object", "properties": { - "remaining": { - "type": "integer", - "description": "The number of IPs that can still be added to the user." - }, - "period": { + "message": { "type": "string", - "description": "The length of time until user can add more IPs." - }, - "price_per_ip": { - "type": "number", - "description": "The current cost to add an IP." + "description": "The reason why the link whitelabel could not be validated." } }, "required": [ - "remaining", - "period", - "price_per_ip" + "message" ] } } }, "required": [ - "results" + "errors" ] }, "examples": { "application/json": { - "results": [ + "errors": [ { - "remaining": 2, - "period": "month", - "price_per_ip": 20 + "message": "internal error getting CNAME" } ] } @@ -8774,65 +7697,72 @@ ] } }, - "/ips/assigned": { - "get": { - "operationId": "GET_ips-assigned", - "summary": "Retrieve all assigned IPs", + "/whitelabel/links/{link_id}/subuser": { + "parameters": [ + { + "name": "link_id", + "in": "path", + "description": "The ID of the branded link you want to associate.", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_whitelabel-links-link_id-subuser", + "summary": "Associate a branded link with a subuser", "tags": [ - "IP Addresses" + "Link branding" ], - "description": "**This endpoint allows you to retrieve only assigned IP addresses.**\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "produces": [ - "application/json" + "description": "**This endpoint allows you to associate a branded link with a subuser account.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", + "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 branded link with." + } + }, + "example": { + "username": "jane@example.com" + } + } + } ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "title": "List all assigned IPs response", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "pools": { - "type": "array", - "description": "The IP pools that this IP address has been added to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "type": "integer", - "description": "The start date that this IP address was entered into warmup." - } - }, - "required": [ - "ip", - "pools", - "warmup", - "start_date" - ] - } + "$ref": "#/definitions/link_branding_200_response" }, "examples": { - "application/json": [ - { - "ip": "167.89.21.3", - "pools": [ - "new_test5" - ], - "warmup": true, - "start_date": 1409616000 + "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" + } } - ] + } } } }, @@ -8843,94 +7773,58 @@ ] } }, - "/ips/{ip_address}": { + "/whitelabel/links/{id}": { "parameters": [ { - "name": "ip_address", + "name": "id", "in": "path", - "description": "The IP address you are retrieving the IP pools for.", + "description": "The ID of the branded link you want to retrieve.", "required": true, - "type": "string" + "type": "integer" } ], "get": { - "operationId": "GET_ips-ip_address", - "summary": "Retrieve all IP pools an IP address belongs to", + "operationId": "GET_whitelabel-links-id", + "summary": "Retrieve a branded link", "tags": [ - "IP Addresses" + "Link branding" ], - "description": "**This endpoint allows you to see which IP pools a particular IP address has been added to.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "produces": [ - "application/json" + "description": "**This endpoint allows you to retrieve a specific branded link by providing its ID.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "subusers": { - "type": "array", - "description": "The subusers that can send email using this IP address.", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for this IP address." - }, - "pools": { - "type": "array", - "description": "The list of IP pools that this IP address belongs to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "type": [ - "integer", - "null" - ], - "description": "The date that the IP address was entered into warmup." - }, - "whitelabeled": { - "type": "boolean", - "description": "Indicates if this IP address has been whitelabeled." - } - }, - "required": [ - "ip", - "subusers", - "rdns", - "pools", - "warmup", - "start_date", - "whitelabeled" - ] + "$ref": "#/definitions/link_branding_200_response" }, "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 + "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" + } + } } } } @@ -8940,22 +7834,14 @@ "Authorization": [] } ] - } - }, - "/ips/pools": { - "post": { - "operationId": "POST_ips-pools", - "summary": "Create an IP pool.", + }, + "patch": { + "operationId": "PATCH_whitelabel-links-id", + "summary": "Update a branded link", "tags": [ - "IP Pools" - ], - "description": "**This endpoint allows you to create an IP pool.**\n\n**Each user can create up to 10 different IP pools.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Link branding" ], + "description": "**This endpoint allows you to update a specific branded link. You can use this endpoint to change a branded link's default status.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "body", @@ -8963,30 +7849,54 @@ "schema": { "type": "object", "properties": { - "name": { - "type": "string", - "description": "The name of your new IP pool.", - "maxLength": 64 + "default": { + "type": "boolean", + "description": "Indicates if the branded link is set as the default. When setting a new default, the existing default link branding will have its default status removed automatically.", + "enum": [ + true, + false + ] } }, - "required": [ - "name" - ], "example": { - "name": "marketing" + "default": true } } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/ip_pool" + "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { - "name": "marketing" + "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" + } + } } } } @@ -8997,34 +7907,23 @@ } ] }, - "get": { - "operationId": "GET_ips-pools", - "summary": "Retrieve all IP pools.", + "delete": { + "operationId": "DELETE_whitelabel-links-id", + "summary": "Delete a branded link", "tags": [ - "IP Pools" + "Link branding" ], - "description": "**This endpoint allows you to retreive all of your IP pools.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", - "produces": [ - "application/json" + "description": "**This endpoint allows you to delete a branded link.**\n\nYour request will receive a response with a 204 status code if the deletion was successful. The call does not return the link's details, so if you wish to record these make sure you call the #endpoint:9Rjrfftdm4Jdzqpko endpoint *before* you request its deletion.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "responses": { - "200": { + "204": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/ip_pool" - } - }, - "examples": { - "application/json": [ - { - "name": "marketing" - }, - { - "name": "transactional" - } - ] + "type": "object" } } }, @@ -9035,81 +7934,55 @@ ] } }, - "/ips/pools/{pool_name}": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "description": "The name of the IP pool that you want to retrieve the IP addresses from.", - "required": true, - "type": "string" - } - ], + "/whitelabel/links/default": { "get": { - "operationId": "GET_ips-pools-pool_name", - "summary": "Retrieve all IPs in a specified pool.", + "operationId": "GET_whitelabel-links-default", + "summary": "Retrieve the default branded link", "tags": [ - "IP Pools" + "Link branding" ], - "description": "**This endpoint allows you to list all of the IP addresses that are in a specific IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", - "produces": [ - "application/json" + "description": "**This endpoint allows you to retrieve the default branded link.**\n\nThe default branded link is the actual URL to be used when sending messages. If you have more than one branded link, the default is determined by the following order:\n\n* The validated branded link marked as `default` (set when you call #endpoint:2gXQQ3udkNjXHWjmk or by calling #endpoint:Hx235Zi3nPGGtpNdM on an existing link)\n* Legacy branded links (migrated from the whitelabel wizard)\n* Default SendGrid-branded links (i.e., `100.ct.sendgrid.net`)\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", + "parameters": [ + { + "name": "domain", + "in": "query", + "description": "The domain to match against when finding the default branded link.", + "type": "string" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "pool_name": { - "type": "string", - "description": "The name of the IP pool.", - "maxLength": 64 - }, - "ips": { - "type": "array", - "description": "The list of IP addresses that belong to this IP pool.", - "items": { - "type": "string" - } - } - }, - "required": [ - "pool_name" - ] - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "description": "The name of the error." - }, - "message": { - "type": "string", - "description": "A message explaining why the IP addresses could not be listed." - } - } - } - } - } + "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { - "errors": [ - { - "field": "error", - "message": "Unable to locate specified IPs Pool" + "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" } - ] + } } } } @@ -9119,82 +7992,56 @@ "Authorization": [] } ] - }, - "put": { - "operationId": "PUT_ips-pools-pool_name", - "summary": "Update an IP pool’s name.", + } + }, + "/whitelabel/links/subuser": { + "get": { + "operationId": "GET_whitelabel-links-subuser", + "summary": "Retrieve a subuser's branded link", "tags": [ - "IP Pools" - ], - "description": "**This endpoint allows you to update the name of an IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Link branding" ], + "description": "**This endpoint allows you to retrieve the branded link associated with a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and then validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name for your IP pool.", - "maxLength": 64 - } - }, - "example": { - "name": "new_pool_name" - } - } + "name": "username", + "in": "query", + "description": "The username of the subuser to retrieve associated branded links for.", + "required": true, + "type": "string" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/ip_pool" + "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { - "name": "new_pool_name" - } - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "null" - }, - "message": { - "type": "string", - "description": "A message explaining why the name of your IP pool could not be updated." - } - } + "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" } } } - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "ip pool not found" - } - ] - } } } }, @@ -9205,22 +8052,19 @@ ] }, "delete": { - "operationId": "DELETE_ips-pools-pool_name", - "summary": "Delete an IP pool.", + "operationId": "DELETE_whitelabel-links-subuser", + "summary": "Disassociate a branded link from a subuser", "tags": [ - "IP Pools" - ], - "description": "**This endpoint allows you to delete an IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", - "produces": [ - "application/json" + "Link branding" ], + "description": "**This endpoint allows you to take a branded link away from a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).\n\nYour request will receive a response with a 204 status code if the disassociation was successful.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + "name": "username", + "in": "query", + "description": "The username of the subuser account that you want to disassociate a branded link from.", + "required": true, + "type": "string" } ], "responses": { @@ -9229,23 +8073,6 @@ "schema": { "type": "object" } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "description": "An error explaining why the pool could not be deleted." - } - } - }, - "examples": { - "application/json": { - "error": "Unable to locate specified IPs Pool" - } - } } }, "security": [ @@ -9255,29 +8082,14 @@ ] } }, - "/ips/pools/{pool_name}/ips": { - "parameters": [ - { - "name": "pool_name", - "in": "path", - "description": "The name of the IP pool that you want to add an IP address to.", - "required": true, - "type": "string" - } - ], + "/ips/warmup": { "post": { - "operationId": "POST_ips-pools-pool_name-ips", - "summary": "Add an IP address to a pool", + "operationId": "POST_ips-warmup", + "summary": "Start warming up an IP address", "tags": [ - "IP Pools" - ], - "description": "**This endpoint allows you to add an IP address to an IP pool.**\n\nYou can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "IP Warmup" ], + "description": "**This endpoint allows you to put an IP address into warmup mode.**", "parameters": [ { "name": "body", @@ -9287,7 +8099,7 @@ "properties": { "ip": { "type": "string", - "description": "The IP address that you want to add to an IP pool." + "description": "The IP address that you want to begin warming up." } }, "example": { @@ -9297,47 +8109,18 @@ } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "pools": { - "type": "array", - "description": "The list of IP pools that this IP address has been added to.", - "items": { - "type": "string" - } - }, - "start_date": { - "type": "integer", - "description": "A unix timestamp indicating when the warmup process began for the IP address." - }, - "warmup": { - "type": "boolean", - "description": "Indicates if the IP address is in warmup." - } - }, - "required": [ - "ip", - "pools", - "start_date", - "warmup" - ] + "$ref": "#/definitions/ip_warmup_response" }, "examples": { - "application/json": { - "ip": "000.00.00.0", - "pools": [ - "test1" - ], - "start_date": 1409616000, - "warmup": true - } + "application/json": [ + { + "ip": "0.0.0.0", + "start_date": 1409616000 + } + ] } }, "404": { @@ -9347,7 +8130,7 @@ "properties": { "errors": { "type": "array", - "description": "The error returned.", + "description": "The errors that were encountered.", "items": { "type": "object", "properties": { @@ -9356,7 +8139,7 @@ }, "message": { "type": "string", - "description": "A message explaining why the IP address could not be added to the IP Pool." + "description": "A message explaining why the IP couldn't entered into warmup mode." } } } @@ -9380,148 +8163,54 @@ "Authorization": [] } ] + }, + "get": { + "operationId": "GET_ips-warmup", + "summary": "Retrieve all IPs currently in warmup", + "tags": [ + "IP Warmup" + ], + "description": "**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**", + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/ip_warmup_response" + }, + "examples": { + "application/json": [ + { + "ip": "0.0.0.0", + "start_date": 1409616000 + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] } }, - "/ips/pools/{pool_name}/ips/{ip}": { + "/ips/warmup/{ip_address}": { "parameters": [ { - "name": "pool_name", - "in": "path", - "description": "The name of the IP pool that you are removing the IP address from.", - "required": true, - "type": "string" - }, - { - "name": "ip", + "name": "ip_address", "in": "path", - "description": "The IP address that you are removing.", + "description": "The IP address that you want to retrieve the warmup status for.", "required": true, "type": "string" } ], - "delete": { - "operationId": "DELETE_ips-pools-pool_name-ips-ip", - "summary": "Remove an IP address from a pool.", - "tags": [ - "IP Pools" - ], - "description": "**This endpoint allows you to remove an IP address from an IP pool.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "error": { - "type": "string", - "description": "An error explaining why the IP address could not be removed from the IP pool." - } - } - }, - "examples": { - "application/json": { - "error": "Unable to locate specified IPs Pool" - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/ips/warmup": { "get": { - "operationId": "GET_ips-warmup", - "summary": "Retrieve all IPs currently in warmup", - "tags": [ - "IP Warmup" - ], - "description": "**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_warmup_response" - }, - "examples": { - "application/json": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "operationId": "POST_ips-warmup", - "summary": "Add an IP to warmup", + "operationId": "GET_ips-warmup-ip_address", + "summary": "Retrieve the warmup status for a specific IP address", "tags": [ "IP Warmup" ], - "description": "**This endpoint allows you to enter an IP address into warmup mode.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", - "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 begin warming up." - } - }, - "example": { - "ip": "0.0.0.0" - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], + "description": "**This endpoint allows you to retrieve the warmup status for a specific IP address.**\n\nYou can retrieve all of your warming IPs using the #endpoint:T8KgmGqsDsx9JTHp8 endpoint.", "responses": { "200": { "description": "", @@ -9553,7 +8242,7 @@ }, "message": { "type": "string", - "description": "A message explaining why the IP couldn't entered into warmup mode." + "description": "A message explaining why the warmup status could not be retrieved." } } } @@ -9577,38 +8266,19 @@ "Authorization": [] } ] - } - }, - "/ips/warmup/{ip_address}": { - "parameters": [ - { - "name": "ip_address", - "in": "path", - "description": "The IP address that you want to retrieve the warmup status for.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_ips-warmup-ip_address", - "summary": "Retrieve warmup status for a specific IP address", + }, + "delete": { + "operationId": "DELETE_ips-warmup-ip_address", + "summary": "Stop warming up an IP address", "tags": [ "IP Warmup" ], - "description": "**This endpoint allows you to retrieve the warmup status for a specific IP address.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], + "description": "**This endpoint allows you to remove an IP address from warmup mode.**\n\nYour request will return a 204 status code if the specified IP was successfully removed from warmup mode. To retrieve details of the IP’s warmup status *before* removing it from warmup mode, call the #endpoint:qf84mxELWH3Prd9JB endpoint.", "responses": { - "200": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/ip_warmup_response" + "type": "object" } }, "404": { @@ -9627,7 +8297,7 @@ }, "message": { "type": "string", - "description": "A message explaining why the warmup status could not be retrieved." + "description": "A message explaining why the IP couldn't be removed from warmup." } } } @@ -9651,23 +8321,45 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_ips-warmup-ip_address", - "summary": "Remove an IP from warmup", + } + }, + "/whitelabel/ips": { + "post": { + "operationId": "POST_whitelabel-ips", + "summary": "Set up reverse DNS", "tags": [ - "IP Warmup" - ], - "description": "**This endpoint allows you to remove an IP address from warmup mode.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", - "produces": [ - "application/json" + "Reverse DNS" ], + "description": "**This endpoint allows you to set up reverse DNS.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "null" + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "The IP address for which you want to set up reverse DNS." + }, + "subdomain": { + "type": "string", + "description": "The subdomain that will be used to send emails from the IP address. This should be the same as the subdomain used to set up an authenticated domain." + }, + "domain": { + "type": "string", + "description": "The root, or sending, domain that will be used to send message from the IP address." + } + }, + "required": [ + "ip", + "domain" + ], + "example": { + "ip": "192.168.1.1", + "subdomain": "email", + "domain": "example.com" + } } }, { @@ -9675,43 +8367,27 @@ } ], "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - }, - "404": { + "201": { "description": "", "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The errors that were encountered.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "null" - }, - "message": { - "type": "string", - "description": "A message explaining why the IP couldn't be removed from warmup." - } - } - } - } - } + "$ref": "#/definitions/reverse_dns" }, "examples": { "application/json": { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] + "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" + } } } } @@ -9721,221 +8397,266 @@ "Authorization": [] } ] - } - }, - "/senders": { - "post": { - "operationId": "POST_senders", - "summary": "Create a Sender Identity", + }, + "get": { + "operationId": "GET_whitelabel-ips", + "summary": "Retrieve all reverse DNS records", "tags": [ - "Sender Identities API" - ], - "description": "**This endpoint allows you to create a new sender identity.**\n\n*You may create up to 100 unique sender identities.*\n\nSender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Reverse DNS" ], + "description": "**This endpoint allows you to retrieve all of the Reverse DNS records created by this account.**\n\nYou may include a search key by using the `ip` query string parameter. This enables you to perform a prefix search for a given IP segment (e.g., `?ip=\"192.\"`).\n\nUse the `limit` query string parameter to reduce the number of records returned. All records will be returned if you have fewer records than the specified limit.\n\nThe `offset` query string parameter allows you to specify a non-zero index from which records will be returned. For example, if you have ten records, `?offset=5` will return the last five records (at indexes 5 through 9). The list starts at index zero.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "nickname": { - "type": "string", - "description": "A nickname for the sender identity. Not used for sending." - }, - "from": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "This is where the email will appear to originate from for your recipient" + "name": "limit", + "in": "query", + "description": "The maximum number of results to retrieve.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "The point in the list of results to begin retrieving IP addresses from.", + "type": "integer" + }, + { + "name": "ip", + "in": "query", + "description": "The IP address segment that you'd like to use in a prefix search.", + "type": "string" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/reverse_dns" + } + }, + "examples": { + "application/json": [ + { + "id": 1, + "ip": "192.168.1.1", + "rdns": "o1.email.example.com", + "users": [ + { + "username": "john@example.com", + "user_id": 7 }, - "name": { - "type": "string", - "description": "This is the name appended to the from email field. IE - Your name or company name." + { + "username": "jane@example.com", + "user_id": 8 } - }, - "required": [ - "email" - ] + ], + "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" + } }, - "reply_to": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "This is the email that your recipient will reply to." + { + "id": 2, + "ip": "192.168.1.2", + "rdns": "o2.email.example.com", + "users": [ + { + "username": "john@example.com", + "user_id": 7 }, - "name": { - "type": "string", - "description": "This is the name appended to the reply to email field. IE - Your name or company name." + { + "username": "jane@example2.com", + "user_id": 9 } - }, - "required": [ - "email" - ] - }, - "address": { - "type": "string", - "description": "The physical address of the sender identity." - }, - "address_2": { - "type": "string", - "description": "Additional sender identity address information." - }, - "city": { - "type": "string", - "description": "The city of the sender identity." - }, - "state": { - "type": "string", - "description": "The state of the sender identity." - }, - "zip": { - "type": "string", - "description": "The zipcode of the sender identity." - }, - "country": { - "type": "string", - "description": "The country of the sender identity." + ], + "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" + } } - }, - "required": [ - "nickname", - "address", - "city", - "country" - ], - "example": { - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States" - } + ] } - }, + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/whitelabel/ips/{id}/validate": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The ID of the reverse DNS record that you would like to validate.", + "required": true, + "type": "string" + } + ], + "post": { + "operationId": "POST_whitelabel-ips-id-validate", + "summary": "Validate a reverse DNS record", + "tags": [ + "Reverse DNS" + ], + "description": "**This endpoint allows you to validate a reverse DNS record.**\n\nAlways check the `valid` property of the response’s `validation_results.a_record` object. This field will indicate whether it was possible to validate the reverse DNS record. If the `validation_results.a_record.valid` is `false`, this indicates only that Twilio SendGrid could not determine the validity your reverse DNS record — it may still be valid.\n\nIf validity couldn’t be determined, you can check the value of `validation_results.a_record.reason` to find out why.\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"#endpoint:ZqgmCfzjZqJYaava7\" endpoint.", + "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/senderID" + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the reverse DNS record." + }, + "valid": { + "type": "boolean", + "description": "Indicates if the reverse DNS record 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 reverse DNS record could be validated.", + "enum": [ + true, + false + ] + }, + "reason": { + "type": [ + "null", + "string" + ], + "description": "The reason the reverse DNS record could not be validated. Is `null` if the reverse DNS record was validated." + } + }, + "required": [ + "valid", + "reason" + ] + } + } + } + }, + "required": [ + "id", + "valid", + "validation_results" + ] }, "examples": { "application/json": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false + "id": 123456, + "valid": false, + "validation_results": { + "a_record": { + "valid": false, + "reason": "Failed to resolve A Record at o1.ptr4283.example.com: lookup o1.ptr4283.example.com on 192.168.0.10:53: no such host" + } + } } } }, - "400": { - "description": "", + "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" - }, - "field": { - "type": "string" + "type": "string", + "description": "A message describing why the reverse DNS could not be validated." } - } + }, + "required": [ + "message" + ] } } - } + }, + "required": [ + "errors" + ] }, "examples": { "application/json": { "errors": [ { - "message": "The JSON you have submitted cannot be parsed.", - "field": "" - }, - { - "message": "You've reached your limit of 100 sender identities. Please delete one or more and try again.", - "field": "" - }, - { - "message": "nickname is required.", - "field": "nickname" - }, - { - "message": "You already have a sender identity with the same nickname.", - "field": "nickname" - }, - { - "message": "from_name is required.", - "field": "from_name" - }, - { - "message": "from_email is required.", - "field": "from_email" - }, - { - "message": "From email is not a valid email address.", - "field": "from_email" - }, - { - "message": "reply_to is required.", - "field": "reply_to" - }, - { - "message": "Reply to email is not a valid email address.", - "field": "reply_to" - }, - { - "message": "address is required.", - "field": "address" - }, - { - "message": "city is required.", - "field": "city" - }, + "message": "Reverse DNS record 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": "country is required.", - "field": "country" + "message": "internal error getting rDNS" } ] } @@ -9947,17 +8668,25 @@ "Authorization": [] } ] - }, + } + }, + "/whitelabel/ips/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The ID of the reverse DNS record that you would like to retrieve.", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_v3-senders", - "summary": "Get all Sender Identities", + "operationId": "GET_whitelabel-ips-id", + "summary": "Retrieve a reverse DNS record", "tags": [ - "Sender Identities API" - ], - "description": "**This endpoint allows you to retrieve a list of all sender identities that have been created for your account.**\n\nSender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", - "produces": [ - "application/json" + "Reverse DNS" ], + "description": "**This endpoint allows you to retrieve a reverse DNS record.**\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"#endpoint:ZqgmCfzjZqJYaava7\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -9967,42 +8696,29 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/definitions/senderID" - } - } - } + "$ref": "#/definitions/reverse_dns" }, "examples": { "application/json": { - "result": [ + "id": 123, + "ip": "192.168.1.1", + "rdns": "o1.email.example.com", + "users": [ { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false + "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" + } } } } @@ -10012,31 +8728,42 @@ "Authorization": [] } ] - } - }, - "/senders/{sender_id}": { - "parameters": [ - { - "name": "sender_id", - "in": "path", - "description": "The ID of the sender identity that you want to update.", - "required": true, - "type": "integer" - } - ], - "patch": { - "operationId": "PATCH_v3-senders-sender_id", - "summary": "Update a Sender Identity", + }, + "delete": { + "operationId": "DELETE_whitelabel-ips-id", + "summary": "Delete a reverse DNS record", "tags": [ - "Sender Identities API" + "Reverse DNS" ], - "description": "**This endpoint allows you to update a sender identity.**\n\nUpdates to `from.email` require re-verification. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.\n\nPartial updates are allowed, but fields that are marked as \"required\" in the POST (create) endpoint must not be nil if that field is included in the PATCH request.", - "consumes": [ - "application/json" + "description": "**This endpoint allows you to delete a reverse DNS record.**\n\nA call to this endpoint will respond with a 204 status code if the deletion was successful.\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"#endpoint:ZqgmCfzjZqJYaava7\" endpoint.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], - "produces": [ - "application/json" + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/validations/email": { + "post": { + "operationId": "POST_validations-email", + "summary": "Validate an email", + "tags": [ + "Email Address Validation" ], + "description": "**This endpoint allows you to validate an email address.**", "parameters": [ { "name": "body", @@ -10044,249 +8771,290 @@ "schema": { "type": "object", "properties": { - "nickname": { + "email": { "type": "string", - "description": "A nickname for the sender identity. Not used for sending." + "description": "The email address that you want to validate." }, - "from": { + "source": { + "type": "string", + "description": "An optional indicator of the email address's source. You may include this if you are capturing email addresses from multiple locations." + } + }, + "required": [ + "email" + ], + "example": { + "email": "example@example.com", + "source": "Signup Form" + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { "type": "object", "properties": { "email": { "type": "string", - "description": "This is where the email will appear to originate from for your recipient" + "format": "email", + "description": "The email address being validated." }, - "name": { + "verdict": { "type": "string", - "description": "This is the name appended to the from email field. IE - Your name or company name." - } - } - }, - "reply_to": { - "type": "object", - "properties": { - "email": { + "enum": [ + "Valid", + "Risky", + "Invalid" + ], + "description": "This field will contain one of three categories: “Valid”, “Risky”, or “Invalid”. These are generic classifications based on the detailed results. You can filter based on this field, but you can also look at more detailed information available in the `score` and `checks` fields." + }, + "score": { + "type": "number", + "minimum": 0, + "maximum": 1, + "description": "This number from 0 to 1 represents the likelihood the email address is valid. Scores closer to 1 are more likely to be valid." + }, + "local": { "type": "string", - "description": "This is the email that your recipient will reply to." + "description": "The local portion of an email address is everything before the @ symbol." }, - "name": { + "host": { "type": "string", - "description": "This is the name appended to the reply to email field. IE - Your name or company name." - } - } - }, - "address": { - "type": "string", - "description": "The physical address of the sender identity." - }, - "address_2": { - "type": "string", - "description": "Additional sender identity address information." - }, - "city": { - "type": "string", - "description": "The city of the sender identity." - }, - "state": { - "type": "string", - "description": "The state of the sender identity." - }, - "zip": { - "type": "string", - "description": "The zipcode of the sender identity." - }, - "country": { - "type": "string", - "description": "The country of the sender identity." + "description": "the domain following the @ symbol in an email address." + }, + "suggestion": { + "type": "string", + "description": "If Twilio SendGrid detects what it believes to be a typo in the address's domain, it will provide a suggested correct spelling in this field." + }, + "checks": { + "type": "object", + "description": "A list of all the checks that ran on the email address. You can use these results to determine your own standards for the message's validity.", + "properties": { + "domain": { + "type": "object", + "description": "The checks performed on the domain portion, after the @ symbol, of the email address.", + "properties": { + "has_valid_address_syntax": { + "type": "boolean", + "description": "Indicates if the domain is properly formatted." + }, + "has_mx_or_a_record": { + "type": "boolean", + "description": "Indicates if the domain has appropriate DNS records needed for email receipt and delivery." + }, + "is_suspected_disposable_address": { + "type": "boolean", + "description": "Indicates if the email address's domain appears to be from a disposable email address service." + } + } + }, + "local_part": { + "type": "object", + "description": "The checks performed on the local portion, before the @ symbol, of the email address.", + "properties": { + "is_suspected_role_address": { + "type": "boolean", + "description": "Indicates if the local portion of the email appears to be a group address such as \"hr,\" \"support,\" or \"admin.\"" + } + } + }, + "additional": { + "type": "object", + "description": "Additional checks performed on the address.", + "properties": { + "has_known_bounces": { + "type": "boolean", + "description": "Indicates if the address has previously bounced a message sent by Twilio SendGrid." + }, + "has_suspected_bounces": { + "type": "boolean", + "description": "Indicates if Twilio SendGrid's machine learning suspects the address will bounce." + } + } + } + } + }, + "source": { + "type": "string", + "description": "An optional indicator of the email address's source. You may include this if you are capturing email addresses from multiple locations." + }, + "ip_address": { + "type": "string", + "description": "The IP address the validation request was made from." + } + } } - }, - "example": { - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States" } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/senderID" }, "examples": { "application/json": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false + "result": { + "email": "jane_doe@gmial.com", + "verdict": "Valid", + "score": 0.79498, + "local": "jane_doe", + "host": "gmial.com", + "suggestion": "gmail.com", + "checks": { + "domain": { + "has_valid_address_syntax": true, + "has_mx_or_a_record": true, + "is_suspected_disposable_address": false + }, + "local_part": { + "is_suspected_role_address": false + }, + "additional": { + "has_known_bounces": false, + "has_suspected_bounces": true + } + }, + "ip_address": "192.168.2.1" + } } } - }, - "400": { - "description": "", + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/validations/email/bulk": { + "post": { + "operationId": "POST_validations-email-bulk", + "summary": "Validate a list of Email Addresses", + "tags": [ + "Email Address Validation" + ], + "description": "**This endpoint allows you to validate a list of email addresses.**", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { "type": "object", "properties": { - "errors": { + "emails": { "type": "array", "items": { "type": "object", "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" + "email": { + "type": "string", + "format": "email" } } } } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "The JSON you have submitted cannot be parsed.", - "field": "" - }, - { - "message": "nickname is required.", - "field": "nickname" - }, - { - "message": "You already have a sender identity with the same nickname.", - "field": "nickname" - }, - { - "message": "from_name is required.", - "field": "from_name" - }, - { - "message": "from_email is required.", - "field": "from_email" - }, - { - "message": "From email is not a valid email address.", - "field": "from_email" - }, - { - "message": "reply_to is required.", - "field": "reply_to" - }, - { - "message": "Reply to email is not a valid email address.", - "field": "reply_to" - }, + }, + "example": { + "emails": [ { - "message": "address is required.", - "field": "address" + "email": "example@example.com" }, { - "message": "city is required.", - "field": "city" + "email": "test@example.com" }, { - "message": "country is required.", - "field": "country" + "email": "example@test.com" } ] } } - }, - "403": { + } + ], + "responses": { + "default": { "description": "", + "schema": {} + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/whitelabel/dns/email": { + "post": { + "operationId": "POST_whitelabel-dns-email", + "summary": "Email DNS records to a co-worker", + "tags": [ + "Email CNAME records" + ], + "description": "**This endpoint is used to share DNS records with a colleagues**\n\nUse this endpoint to send SendGrid-generated DNS record information to a co-worker so they can enter it into your DNS provider to validate your domain and link branding. \n\nWhat type of records are sent will depend on whether you have chosen Automated Security or not. When using Automated Security, SendGrid provides you with three CNAME records. If you turn Automated Security off, you are instead given TXT and MX records.\n\nIf you pass a `link_id` to this endpoint, the generated email will supply the DNS records necessary to complete [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setup. If you pass a `domain_id` to this endpoint, the generated email will supply the DNS records needed to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/). Passing both IDs will generate an email with the records needed to complete both setup steps.\n\nYou can retrieve all your domain IDs from the returned `id` fields for each domain using the \"#endpoint:2uc5Dx5bR4iDqCzS9\" endpoint. You can retrieve all of your link IDs using the \"#endpoint:wQKA6mJBDXXycDkgC\" endpoint.", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { "type": "object", "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } + "link_id": { + "type": "integer", + "minimum": 0, + "desc": "The ID of the branded link." + }, + "domain_id": { + "type": "integer", + "minimum": 0, + "description": "The ID of your SendGrid domain record." + }, + "email": { + "type": "string", + "format": "email", + "description": "The email address to send the DNS information to." + }, + "message": { + "type": "string", + "default": "Please set these DNS records in our hosting solution.", + "description": "A custom text block to include in the email body sent with the records." } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "You may only update a sender identity when it is unlocked.", - "field": "locked" - } - ] + }, + "required": [ + "link_id", + "domain_id", + "email" + ], + "example": { + "link_id": 29719392, + "domain_id": 46873408, + "email": "my_colleague@example.com", + "message": "DNS Record for verification" } } + } + ], + "responses": { + "204": { + "description": "" }, - "404": { + "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } + "type": "object", + "properties": { + "error": { + "type": "string" + }, + "field": { + "type": "string" } } } } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "resource not found", - "field": "id" - } - ] - } } } }, @@ -10295,59 +9063,168 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_v3-senders-sender_id", - "summary": "Delete a Sender Identity", + } + }, + "/ips/pools": { + "post": { + "operationId": "POST_ips-pools", + "summary": "Create an IP pool", "tags": [ - "Sender Identities API" - ], - "description": "**This endoint allows you to delete one of your sender identities.**\n\nSender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", - "produces": [ - "application/json" + "IP Pools" ], + "description": "**This endpoint allows you to create an IP pool.**\n\nBefore you can create an IP pool, you need to activate the IP in your SendGrid account: \n\n1. Log into your SendGrid account. \n1. Navigate to **Settings** and then select **IP Addresses**. \n1. Find the IP address you want to activate and then click **Edit**. \n1. Check **Allow my account to send mail using this IP address**.\n1. Click **Save**.", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of your new IP pool.", + "maxLength": 64 + } + }, + "required": [ + "name" + ], + "example": { + "name": "marketing" + } + } } ], "responses": { - "204": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/ip_pool_response" + }, + "examples": { + "application/json": { + "name": "marketing" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_ips-pools", + "summary": "Retrieve all IP pools", + "tags": [ + "IP Pools" + ], + "description": "**This endpoint allows you to get all of your IP pools.**", + "responses": { + "200": { "description": "", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/ip_pool_response" + } + }, + "examples": { + "application/json": [ + { + "name": "marketing" + }, + { + "name": "transactional" + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/ips/pools/{pool_name}/ips": { + "parameters": [ + { + "name": "pool_name", + "in": "path", + "description": "The name of the IP pool you want to add the address to. If the name contains spaces, they must be URL encoded (e.g., \"Test Pool\" becomes \"Test%20Pool\").", + "required": true, + "type": "string" + } + ], + "post": { + "operationId": "POST_ips-pools-pool_name-ips", + "summary": "Add an IP address to a pool", + "tags": [ + "IP Pools" + ], + "description": "**This endpoint allows you to add an IP address to an IP pool.**\n\nYou can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made.\n\nBefore you can add an IP to a pool, you need to activate it in your SendGrid account:\n\n1. Log into your SendGrid account. \n1. Navigate to **Settings** and then select **IP Addresses**. \n1. Find the IP address you want to activate and then click **Edit**. \n1. Check **Allow my account to send mail using this IP address**.\n1. Click **Save**.\n\nYou can retrieve all of your available IP addresses from the \"#endpoint:ebQqc7eNTRxxpCy3G\" endpoint.", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { "type": "object", - "properties": {} + "properties": { + "ip": { + "type": "string", + "description": "The IP address that you want to add to the named pool." + } + }, + "example": { + "ip": "0.0.0.0" + } } - }, - "403": { + } + ], + "responses": { + "201": { "description": "", "schema": { "type": "object", "properties": { - "errors": { + "ip": { + "type": "string", + "description": "The IP address." + }, + "pools": { "type": "array", + "description": "The IP pools that this IP address has been added to.", "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } + "type": "string" } + }, + "start_date": { + "type": "integer", + "description": "A Unix timestamp indicating when the warmup process began for the added IP address." + }, + "warmup": { + "type": "boolean", + "description": "Indicates if the IP address is in warmup." } - } + }, + "required": [ + "ip", + "pools", + "start_date", + "warmup" + ] }, "examples": { "application/json": { - "errors": [ - { - "message": "You may only delete a sender identity when it is unlocked.", - "field": "locked" - } - ] + "ip": "000.00.00.0", + "pools": [ + "test1" + ], + "start_date": 1409616000, + "warmup": true } } }, @@ -10358,14 +9235,16 @@ "properties": { "errors": { "type": "array", + "description": "The error returned.", "items": { "type": "object", "properties": { - "message": { - "type": "string" - }, "field": { - "type": "string" + "type": "null" + }, + "message": { + "type": "string", + "description": "A message explaining why the IP address could not be added to the IP Pool." } } } @@ -10376,8 +9255,8 @@ "application/json": { "errors": [ { - "message": "resource not found", - "field": "id" + "field": null, + "message": "resource not found" } ] } @@ -10389,50 +9268,43 @@ "Authorization": [] } ] - }, + } + }, + "/ips/pools/{pool_name}": { + "parameters": [ + { + "name": "pool_name", + "in": "path", + "description": "The name of the IP pool that you want to retrieve the IP addresses for.", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_v3-senders-sender_id", - "summary": "View a Sender Identity", + "operationId": "GET_ips-pools-pool_name", + "summary": "Retrieve all the IPs in a specified pool", "tags": [ - "Sender Identities API" - ], - "description": "**This endpoint allows you to retrieve a specific sender identity.**\n\nSender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "IP Pools" ], + "description": "**This endpoint allows you to get all of the IP addresses that are in a specific IP pool.**", "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/senderID" - }, - "examples": { - "application/json": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" + "type": "object", + "properties": { + "pool_name": { + "type": "string", + "description": "The name of the IP pool.", + "maxLength": 64 }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false + "ips": { + "type": "array", + "description": "The IP addresses that belong to this pool.", + "items": { + "type": "string" + } + } } } }, @@ -10446,11 +9318,13 @@ "items": { "type": "object", "properties": { - "message": { - "type": "string" - }, "field": { - "type": "string" + "type": "string", + "description": "The name of the error." + }, + "message": { + "type": "string", + "description": "A message explaining why the IP addresses could not be listed." } } } @@ -10461,8 +9335,8 @@ "application/json": { "errors": [ { - "message": "resource not found", - "field": "id" + "field": "error", + "message": "Unable to locate specified IPs Pool" } ] } @@ -10474,42 +9348,46 @@ "Authorization": [] } ] - } - }, - "/senders/{sender_id}/resend_verification": { - "parameters": [ - { - "name": "sender_id", - "in": "path", - "description": "The ID of the sender identity for which you would like to resend a verification email.", - "required": true, - "type": "integer" - } - ], - "post": { - "operationId": "POST_v3-senders-sender_id-resend_verification", - "summary": "Resend Sender Identity Verification", + }, + "put": { + "operationId": "PUT_ips-pools-pool_name", + "summary": "Rename an IP pool", "tags": [ - "Sender Identities API" - ], - "description": "**This enpdoint allows you to resend a sender identity verification email.**\n\nSender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", - "produces": [ - "application/json" + "IP Pools" ], + "description": "**This endpoint allows you to update the name of an IP pool.**", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The new name for your IP pool.", + "maxLength": 64 + } + }, + "example": { + "name": "new_pool_name" + } + } } ], "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "object", - "properties": {} + "$ref": "#/definitions/ip_pool_response" + }, + "examples": { + "application/json": { + "name": "new_pool_name" + } } }, - "400": { + "404": { "description": "", "schema": { "type": "object", @@ -10519,11 +9397,12 @@ "items": { "type": "object", "properties": { - "message": { - "type": "string" - }, "field": { - "type": "string" + "type": "null" + }, + "message": { + "type": "string", + "description": "A message explaining why the name of your IP pool could not be updated." } } } @@ -10534,42 +9413,48 @@ "application/json": { "errors": [ { - "message": "The Sender Identity is already verified. No email sent.", - "field": "" + "field": null, + "message": "ip pool not found" } ] } } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_ips-pools-pool_name", + "summary": "Delete an IP pool", + "tags": [ + "IP Pools" + ], + "description": "**This endpoint allows you to delete an IP pool.**", + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" + } }, "404": { "description": "", "schema": { "type": "object", "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } + "error": { + "type": "string", + "description": "An error explaining why the pool could not be deleted." } } }, "examples": { "application/json": { - "errors": [ - { - "message": "resource not found", - "field": "id" - } - ] + "error": "Unable to locate specified IPs Pool" } } } @@ -10581,46 +9466,51 @@ ] } }, - "/user/settings/enforced_tls": { - "get": { - "operationId": "GET_user-settings-enforced_tls", - "summary": "Retrieve current Enforced TLS settings.", + "/ips/pools/{pool_name}/ips/{ip}": { + "parameters": [ + { + "name": "pool_name", + "in": "path", + "description": "The name of the IP pool that you are removing the IP address from.", + "required": true, + "type": "string" + }, + { + "name": "ip", + "in": "path", + "description": "The IP address that you wish to remove.", + "required": true, + "type": "string" + } + ], + "delete": { + "operationId": "DELETE_ips-pools-pool_name-ips-ip", + "summary": "Remove an IP address from a pool", "tags": [ - "Settings - Enforced TLS" - ], - "description": "**This endpoint allows you to retrieve your current Enforced TLS settings.**\n\nThe Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS.\n\n**Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "IP Pools" ], + "description": "**This endpoint allows you to remove an IP address from an IP pool.**", "responses": { - "200": { + "204": { + "description": "", + "schema": { + "type": "object" + } + }, + "404": { "description": "", "schema": { "type": "object", "properties": { - "require_tls": { - "type": "boolean", - "description": "Indicates if the recipient is required to support TLS." - }, - "require_valid_cert": { - "type": "boolean", - "description": "Indicates if the recipient is required to have a valid certificate." + "error": { + "type": "string", + "description": "An error explaining why the IP address could not be removed from the IP pool." } - }, - "required": [ - "require_tls", - "require_valid_cert" - ] + } }, "examples": { "application/json": { - "require_tls": false, - "require_valid_cert": false + "error": "Unable to locate specified IPs Pool" } } } @@ -10630,20 +9520,16 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_user-settings-enforced_tls", - "summary": "Update Enforced TLS settings", + } + }, + "/ips": { + "post": { + "operationId": "POST_ips", + "summary": "Add IPs", "tags": [ - "Settings - Enforced TLS" - ], - "description": "**This endpoint allows you to update your current Enforced TLS settings.**\n\nThe Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS.\n\n**Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "IP Addresses" ], + "description": "**This endpoint is for adding a(n) IP Address(es) to your account.**", "parameters": [ { "name": "body", @@ -10651,105 +9537,271 @@ "schema": { "type": "object", "properties": { - "require_tls": { - "type": "boolean", - "description": "Indicates if you want to require your recipients to support TLS. " + "count": { + "type": "integer", + "description": "The amount of IPs to add to the account." + }, + "subusers": { + "type": "array", + "description": "Array of usernames to be assigned a send IP.", + "items": { + "type": "string" + } }, - "require_valid_cert": { + "warmup": { "type": "boolean", - "description": "Indicates if you want to require your recipients to have a valid certificate." + "default": false, + "description": "Whether or not to warmup the IPs being added." } }, + "required": [ + "count" + ], "example": { - "require_tls": true, - "require_valid_cert": false + "count": 90323478, + "subusers": [ + "subuser1", + "subuser2" + ], + "warmup": true, + "user_can_send": true } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "201": { "description": "", "schema": { "type": "object", "properties": { - "require_tls": { - "type": "boolean", - "description": "Indicates if your recipients are required to support TLS." + "ips": { + "type": "array", + "description": "List of IP objects.", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "IP added to account." + }, + "subusers": { + "type": "array", + "description": "Array of usernames assigned a send IP.", + "items": { + "type": "string" + } + } + }, + "required": [ + "ip", + "subusers" + ] + } + }, + "remaining_ips": { + "type": "integer", + "description": "The number of IPs that can still be added to the user." }, - "require_valid_cert": { + "warmup": { "type": "boolean", - "description": "Indicates if your recipients are required to have a valid certificate." + "description": "Whether or not the IPs are being warmed up." } }, "required": [ - "require_tls", - "require_valid_cert" + "ips", + "remaining_ips", + "warmup" ] }, "examples": { "application/json": { - "require_tls": true, - "require_valid_cert": false + "ips": [ + { + "ip": "1.2.3.4", + "subusers": [ + "user", + "subuser1" + ] + }, + { + "ip": "1.2.3.5", + "subusers": [ + "user", + "subuser1" + ] + } + ], + "remaining_ips": 1, + "warmup": true } } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/user/webhooks/parse/settings": { - "post": { - "operationId": "POST_user-webhooks-parse-settings", - "summary": "Create a parse setting", + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/error_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "one or more subusers do not belong to this user" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_ips", + "summary": "Retrieve all IP addresses", "tags": [ - "Settings - Inbound Parse" - ], - "description": "**This endpoint allows you to create a new inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "IP Addresses" ], + "description": "**This endpoint allows you to retrieve a list of all assigned and unassigned IPs.**\n\nResponse includes warm up status, pools, assigned subusers, and reverse DNS info. The start_date field corresponds to when warmup started for that IP.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/parse-setting", - "example": { - "hostname": "myhostname.com", - "url": "http://email.myhosthame.com", - "spam_check": true, - "send_raw": false - } - } + "name": "ip", + "in": "query", + "description": "The IP address to get", + "type": "string" }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "exclude_whitelabels", + "in": "query", + "description": "Should we exclude reverse DNS records (whitelabels)?", + "type": "boolean" + }, + { + "name": "limit", + "in": "query", + "description": "The number of IPs you want returned at the same time.", + "type": "integer", + "default": 10 + }, + { + "name": "offset", + "in": "query", + "description": "The offset for the number of IPs that you are requesting.", + "type": "integer", + "default": 0 + }, + { + "name": "subuser", + "in": "query", + "description": "The subuser you are requesting for.", + "type": "string" + }, + { + "name": "sort_by_direction", + "in": "query", + "description": "The direction to sort the results.", + "type": "string", + "enum": [ + "desc", + "asc" + ] } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "$ref": "#/definitions/parse-setting" + "type": "array", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "An IP address." + }, + "subusers": { + "type": "array", + "description": "The subusers that are able to send email from this IP.", + "items": { + "type": "string" + } + }, + "rdns": { + "type": "string", + "description": "The reverse DNS record for this IP address." + }, + "pools": { + "type": "array", + "description": "The IP pools that this IP has been added to.", + "items": { + "type": "string" + } + }, + "warmup": { + "type": "boolean", + "description": "Indicates if this IP address is currently warming up." + }, + "start_date": { + "type": [ + "number", + "null" + ], + "description": "The date that the IP address was entered into warmup." + }, + "whitelabeled": { + "type": "boolean", + "description": "Indicates if this IP address is associated with a reverse DNS record." + }, + "assigned_at": { + "type": [ + "integer", + "null" + ], + "description": "The date that the IP address was assigned to the user." + } + }, + "required": [ + "ip", + "subusers", + "pools", + "warmup", + "start_date", + "whitelabeled", + "assigned_at" + ] + } }, "examples": { - "application/json": { - "url": "http://email.myhostname.com", - "hostname": "myhostname.com", - "spam_check": false, - "send_raw": true - } + "application/json": [ + { + "ip": "192.168.1.1", + "pools": [ + "pool1", + "pool2" + ], + "whitelabeled": false, + "start_date": 1409616000, + "subusers": [ + "tim@sendgrid.net" + ], + "warmup": false, + "assigned_at": 1482883200 + }, + { + "ip": "208.115.214.22", + "pools": [], + "whitelabeled": true, + "rdns": "o1.email.burgermail.com", + "start_date": 1409616000, + "subusers": [], + "warmup": false, + "assigned_at": 1482883200 + } + ] } } }, @@ -10758,45 +9810,59 @@ "Authorization": [] } ] - }, + } + }, + "/ips/remaining": { "get": { - "operationId": "GET_user-webhooks-parse-settings", - "summary": "Retrieve all parse settings", + "operationId": "GET_ips-remaining", + "summary": "Get remaining IPs count", "tags": [ - "Settings - Inbound Parse" - ], - "description": "**This endpoint allows you to retrieve all of your current inbound parse settings.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "IP Addresses" ], + "description": "**This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs.**", "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { - "result": { + "results": { "type": "array", - "description": "The list of your current inbound parse settings.", "items": { - "$ref": "#/definitions/parse-setting" + "type": "object", + "properties": { + "remaining": { + "type": "integer", + "description": "The number of IPs that can still be added to the user." + }, + "period": { + "type": "string", + "description": "The length of time until user can add more IPs." + }, + "price_per_ip": { + "type": "number", + "description": "The current cost to add an IP." + } + }, + "required": [ + "remaining", + "period", + "price_per_ip" + ] } } - } + }, + "required": [ + "results" + ] }, "examples": { "application/json": { - "result": [ + "results": [ { - "url": "http://mydomain.com/parse", - "hostname": "mail.mydomain.com", - "spam_check": true, - "send_raw": true + "remaining": 2, + "period": "month", + "price_per_ip": 20 } ] } @@ -10810,44 +9876,62 @@ ] } }, - "/user/webhooks/parse/settings/{hostname}": { - "parameters": [ - { - "name": "hostname", - "in": "path", - "description": "The hostname associated with the inbound parse setting that you would like to retrieve.", - "required": true, - "type": "string" - } - ], + "/ips/assigned": { "get": { - "operationId": "GET_user-webhooks-parse-settings-hostname", - "summary": "Retrieve a specific parse setting", + "operationId": "GET_ips-assigned", + "summary": "Retrieve all assigned IPs", "tags": [ - "Settings - Inbound Parse" - ], - "description": "**This endpoint allows you to retrieve a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "IP Addresses" ], + "description": "**This endpoint allows you to retrieve only assigned IP addresses.**\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/parse-setting" + "type": "array", + "title": "List all assigned IPs response", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "The IP address." + }, + "pools": { + "type": "array", + "description": "The IP pools that this IP address has been added to.", + "items": { + "type": "string" + } + }, + "warmup": { + "type": "boolean", + "description": "Indicates if this IP address is currently warming up." + }, + "start_date": { + "type": "integer", + "description": "The start date that this IP address was entered into warmup." + } + }, + "required": [ + "ip", + "pools", + "warmup", + "start_date" + ] + } }, "examples": { - "application/json": { - "url": "http://mydomain.com/parse", - "hostname": "mail.mydomain.com", - "spam_check": true, - "send_raw": true - } + "application/json": [ + { + "ip": "167.89.21.3", + "pools": [ + "new_test5" + ], + "warmup": true, + "start_date": 1409616000 + } + ] } } }, @@ -10856,49 +9940,93 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_user-webhooks-parse-settings-hostname", - "summary": "Update a parse setting", + } + }, + "/ips/{ip_address}": { + "parameters": [ + { + "name": "ip_address", + "in": "path", + "description": "The IP address you are retrieving the IP pools for.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_ips-ip_address", + "summary": "Retrieve all IP pools an IP address belongs to", "tags": [ - "Settings - Inbound Parse" - ], - "description": "**This endpoint allows you to update a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/parse-setting", - "example": { - "url": "http://newdomain.com/parse", - "spam_check": false, - "send_raw": true - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "IP Addresses" ], + "description": "**This endpoint allows you to see which IP pools a particular IP address has been added to.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/parse-setting" + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "The IP address." + }, + "subusers": { + "type": "array", + "description": "The subusers that can send email using this IP address.", + "items": { + "type": "string" + } + }, + "rdns": { + "type": "string", + "description": "The reverse DNS record for this IP address." + }, + "pools": { + "type": "array", + "description": "The list of IP pools that this IP address belongs to.", + "items": { + "type": "string" + } + }, + "warmup": { + "type": "boolean", + "description": "Indicates if this IP address is currently warming up." + }, + "start_date": { + "type": [ + "integer", + "null" + ], + "description": "The date that the IP address was entered into warmup." + }, + "whitelabeled": { + "type": "boolean", + "description": "Indicates if this IP address is associated with a reverse DNS record." + } + }, + "required": [ + "ip", + "subusers", + "rdns", + "pools", + "warmup", + "start_date", + "whitelabeled" + ] }, "examples": { "application/json": { - "url": "http://mydomain.com/parse", - "hostname": "mail.mydomain.com", - "spam_check": true, - "send_raw": true + "ip": "000.00.00.0", + "subusers": [ + "subuser1", + "subuser2" + ], + "rdns": "o1.em.example.com", + "pools": [ + "test1" + ], + "warmup": false, + "start_date": null, + "whitelabeled": true } } } @@ -10908,58 +10036,47 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_user-webhooks-parse-settings-hostname", - "summary": "Delete a parse setting", - "tags": [ - "Settings - Inbound Parse" - ], - "description": "**This endpoint allows you to delete a specific inbound parse setting.**\n\nThe inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html).", - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ] } }, - "/mail_settings": { + "/whitelabel/domains": { "get": { - "operationId": "GET_mail_settings", - "summary": "Retrieve all mail settings", + "operationId": "GET_whitelabel-domains", + "summary": "List all authenticated domains", "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to retrieve a list of all domains you have authenticated.**", "parameters": [ { "name": "limit", "in": "query", - "description": "The number of settings to return.", + "description": "Number of domains to return.", "type": "integer" }, { "name": "offset", "in": "query", - "description": "Where in the list of results to begin displaying settings.", + "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 an authenticated domain.", + "type": "string" + }, + { + "name": "domain", + "in": "query", + "description": "Search for authenticated domains.", + "type": "string" + }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -10968,146 +10085,80 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "The list of all mail settings.", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the mail setting." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this mail setting is currently enabled." - }, - "name": { - "type": "string", - "description": "The name of the mail setting." - }, - "description": { - "type": "string", - "description": "A description of the mail setting." - } - }, - "required": [ - "title", - "enabled", - "name", - "description" - ] - } - } - }, - "required": [ - "result" - ] + "$ref": "#/definitions/domain-authentication-200-response" }, "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." + "application/json": [ + { + "id": 1, + "user_id": 7, + "subdomain": "mail", + "domain": "example.com", + "username": "jane@example.com", + "ips": [ + "192.168.1.1", + "192.168.1.2" + ], + "custom_spf": true, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": true, + "dns": { + "mail_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "u7.wl.sendgrid.net" + }, + "dkim1": { + "valid": true, + "type": "cname", + "host": "s1._domainkey.example.com", + "data": "s1._domainkey.u7.wl.sendgrid.net" + }, + "dkim2": { + "valid": true, + "type": "cname", + "host": "s2._domainkey.example.com", + "data": "s2._domainkey.u7.wl.sendgrid.net" + } } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/mail_settings/bcc": { - "get": { - "operationId": "GET_mail_settings-bcc", - "summary": "Retrieve all BCC mail settings", - "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_bcc" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "enabled": false - } + }, + { + "id": 2, + "user_id": 8, + "subdomain": "new", + "domain": "example2.com", + "username": "john@example2.com", + "ips": [], + "custom_spf": false, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": false, + "dns": { + "mail_cname": { + "valid": false, + "type": "mx", + "host": "news.example2.com", + "data": "sendgrid.net" + }, + "dkim1": { + "valid": false, + "type": "txt", + "host": "example2.com", + "data": "k=rsa; t=s; p=publicKey" + }, + "dkim2": { + "valid": false, + "type": "txt", + "host": "example2.com", + "data": "k=rsa; t=s p=publicKey" + } + } + } + ] } } }, @@ -11117,28 +10168,70 @@ } ] }, - "patch": { - "operationId": "PATCH_mail_settings-bcc", - "summary": "Update BCC mail settings", + "post": { + "operationId": "POST_whitelabel-domains", + "summary": "Authenticate a domain", "tags": [ - "Settings - Mail" - ], - "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’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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to authenticate a domain.**\n\nIf you are authenticating a domain for a subuser, you have two options:\n1. Use the \"username\" parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain.\n2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain.", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/mail_settings_patch", + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": "Domain being authenticated." + }, + "subdomain": { + "type": "string", + "description": "The subdomain to use for this authenticated domain." + }, + "username": { + "type": "string", + "description": "The username associated with this domain." + }, + "ips": { + "type": "array", + "description": "The IP addresses that will be included in the custom SPF record for this authenticated domain.", + "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 authenticated domains set up for manual security." + }, + "default": { + "type": "boolean", + "description": "Whether to use this authenticated domain as the fallback if no authenticated domains 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." + }, + "custom_dkim_selector": { + "type": "string", + "description": "Add a custom DKIM selector. Accepts three letters or numbers." + } + }, + "required": [ + "domain" + ], "example": { - "enabled": false, - "email": "email@example.com" + "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 } } }, @@ -11147,15 +10240,44 @@ } ], "responses": { - "200": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_patch" + "$ref": "#/definitions/authentication::domain" }, "examples": { "application/json": { - "email": "example@example.com", - "enabled": false + "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" + } + } } } } @@ -11167,17 +10289,22 @@ ] } }, - "/mail_settings/address_whitelist": { + "/whitelabel/domains/{domain_id}": { + "parameters": [ + { + "name": "domain_id", + "in": "path", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_mail_settings-address_whitelist", - "summary": "Retrieve address whitelist mail settings", + "operationId": "GET_whitelabel-domains-domain_id", + "summary": "Retrieve an authenticated domain", "tags": [ - "Settings - Mail" - ], - "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 “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.\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).", - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to retrieve a specific authenticated domain.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -11187,15 +10314,7 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_address_whitelabel" - }, - "examples": { - "application/json": { - "enabled": false, - "list": [ - "example.com" - ] - } + "$ref": "#/definitions/authentication::domain" } } }, @@ -11206,18 +10325,12 @@ ] }, "patch": { - "operationId": "PATCH_mail_settings-address_whitelist", - "summary": "Update address whitelist mail settings", + "operationId": "PATCH_whitelabel-domains-domain_id", + "summary": "Update an authenticated domain", "tags": [ - "Settings - Mail" - ], - "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 “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.\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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to update the settings for an authenticated domain.**", "parameters": [ { "name": "body", @@ -11225,24 +10338,20 @@ "schema": { "type": "object", "properties": { - "enabled": { + "default": { "type": "boolean", - "description": "Indicates if your email address whitelist is enabled." + "default": false, + "description": "Indicates whether this is the default authenticated domain." }, - "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" - } + "custom_spf": { + "type": "boolean", + "default": false, + "description": "Indicates whether to generate a custom SPF record for manual security." } }, "example": { - "enabled": true, - "list": [ - "email1@example.com", - "example.com" - ] + "default": false, + "custom_spf": true } } }, @@ -11254,15 +10363,106 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_address_whitelabel" + "$ref": "#/definitions/domain-authentication-200-response" }, "examples": { - "application/json": { - "enabled": true, - "list": [ - "email1@example.com" - ] - } + "application/json": [ + { + "id": 1, + "user_id": 7, + "subdomain": "mail", + "domain": "example.com", + "username": "jane@example.com", + "ips": [ + "192.168.1.1", + "192.168.1.2" + ], + "custom_spf": true, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": true, + "dns": { + "mail_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "u7.wl.sendgrid.net" + }, + "dkim1": { + "valid": true, + "type": "cname", + "host": "s1._domainkey.example.com", + "data": "s1._domainkey.u7.wl.sendgrid.net" + }, + "dkim2": { + "valid": true, + "type": "cname", + "host": "s2._domainkey.example.com", + "data": "s2._domainkey.u7.wl.sendgrid.net" + } + } + }, + { + "id": 2, + "user_id": 8, + "subdomain": "new", + "domain": "example2.com", + "username": "john@example2.com", + "ips": [], + "custom_spf": false, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": false, + "dns": { + "mail_cname": { + "valid": false, + "type": "mx", + "host": "news.example2.com", + "data": "sendgrid.net" + }, + "dkim1": { + "valid": false, + "type": "txt", + "host": "example2.com", + "data": "k=rsa; t=s; p=publicKey" + }, + "dkim2": { + "valid": false, + "type": "txt", + "host": "example2.com", + "data": "k=rsa; t=s p=publicKey" + } + } + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_whitelabel-domains-domain_id", + "summary": "Delete an authenticated domain.", + "tags": [ + "Domain Authentication" + ], + "description": "**This endpoint allows you to delete an authenticated domain.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" } } }, @@ -11273,18 +10473,21 @@ ] } }, - "/mail_settings/footer": { + "/whitelabel/domains/default": { "get": { - "operationId": "GET_mail_settings-footer", - "summary": "Retrieve footer mail settings", + "operationId": "GET_whitelabel-domains-default", + "summary": "Get the default authentication", "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to retrieve the default authentication for a domain.**\n\nTODO: Check this URL. Does it have a query param, or does the domain go in the URL path? If so, where?", "parameters": [ + { + "name": "domain", + "in": "query", + "description": "The domain to find a default authentication.", + "type": "string" + }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -11293,14 +10496,7 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_footer" - }, - "examples": { - "application/json": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - } + "$ref": "#/definitions/domain_authentication:domain_spf" } } }, @@ -11309,30 +10505,42 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_mail_settings-footer", - "summary": "Update footer mail settings", + } + }, + "/whitelabel/domains/{id}/ips": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the domain to which you are adding an IP", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_whitelabel-domains-id-ips", + "summary": "Add an IP to an authenticated domain", "tags": [ - "Settings - Mail" - ], - "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’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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to add an IP address to an authenticated domain.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/mail_settings_footer", + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." + } + }, + "required": [ + "ip" + ], "example": { - "enabled": true, - "html_content": "...", - "plain_content": "..." + "ip": "192.168.0.1" } } }, @@ -11344,13 +10552,47 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_footer" + "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" + "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 + } + } } } } @@ -11362,17 +10604,28 @@ ] } }, - "/mail_settings/forward_spam": { - "get": { - "operationId": "GET_mail_settings-forward_spam", - "summary": "Retrieve forward spam mail settings", + "/whitelabel/domains/{id}/ips/{ip}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "ip", + "in": "path", + "required": true, + "type": "string" + } + ], + "delete": { + "operationId": "DELETE_whitelabel-domains-id-ips-ip", + "summary": "Remove an IP from an authenticated domain.", "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to remove an IP address from that domain's authentication.**\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain to delete the IP from. |\n| ip | string | IP to remove from the domain. |", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -11382,61 +10635,47 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" + "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { - "email": "", - "enabled": true - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "operationId": "PATCH_mail_settings-forward_spam", - "summary": "Update forward spam mail settings", - "tags": [ - "Settings - Mail" - ], - "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’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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/mail_settings_forward_spam", - "example": { - "email": "", - "enabled": false - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_forward_spam" - }, - "examples": { - "application/json": { - "email": "", - "enabled": false + "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 + } + } } } } @@ -11448,17 +10687,23 @@ ] } }, - "/mail_settings/plain_content": { - "get": { - "operationId": "GET_mail_settings-plain_content", - "summary": "Retrieve plain content mail settings", + "/whitelabel/domains/{id}/validate": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the domain to validate.", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_whitelabel-domains-id-validate", + "summary": "Validate a domain authentication.", "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to validate an authenticated domain. If it fails, it will return an error message describing why the domain could not be validated.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -11470,74 +10715,129 @@ "schema": { "type": "object", "properties": { - "enabled": { + "id": { + "type": "integer", + "description": "The ID of the authenticated domain." + }, + "valid": { "type": "boolean", - "description": "Indicates if the Plain Content mail setting is enabled." + "description": "Indicates if this is a valid authenticated domain." + }, + "validation_results": { + "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 authenticated domain.", + "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 authenticated domain.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the DNS record is valid." + }, + "reason": { + "type": "null" + } + } + }, + "dkim2": { + "type": "object", + "description": "A DNS record for this authenticated domain.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the DNS record is valid." + }, + "reason": { + "type": "null" + } + } + }, + "spf": { + "type": "object", + "description": "The SPF record for the authenticated domain.", + "properties": { + "valid": { + "type": "boolean", + "description": "Indicates if the SPF record is valid." + }, + "reason": { + "type": "null" + } + } + } + } } } }, "examples": { "application/json": { - "enabled": false - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "operationId": "PATCH_mail_settings-plain_content", - "summary": "Update plain content mail settings", - "tags": [ - "Settings - Mail" - ], - "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’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).", - "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." + "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 + } } - }, - "example": { - "enabled": false } } }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { + "500": { "description": "", "schema": { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if your Plain Content mail setting is enabled." + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "A message explaining the reason for the error." + } + }, + "required": [ + "message" + ] + } } } }, "examples": { "application/json": { - "enabled": false + "errors": [ + { + "message": "internal error getting TXT" + } + ] } } } @@ -11549,101 +10849,68 @@ ] } }, - "/mail_settings/spam_check": { + "/whitelabel/domains/subuser": { "get": { - "operationId": "GET_mail_settings-spam_check", - "summary": "Retrieve spam check mail settings", + "operationId": "GET_whitelabel-domains-subuser", + "summary": "List the authenticated domain associated with the given user.", "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to retrieve all of the authenticated domains that have been assigned to a specific subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate a authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The the parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "username", + "in": "query", + "description": "Username for the subuser to find associated authenticated domain.", + "required": true, + "type": "string" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_spam_check" + "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "operationId": "PATCH_mail_settings-spam_check", - "summary": "Update spam check mail settings", - "tags": [ - "Settings - Mail" - ], - "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’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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you want the spam check mail setting to be enabled or not." - }, - "url": { - "type": "string", - "description": "The Inbound Parse URL where you would like your spam reports to be sent to." - }, - "max_score": { - "type": "integer", - "default": 5, - "description": "The new max score, or spam threshold that you would like to set for the spam checker.", - "minimum": 1, - "maximum": 10 + "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 + } } - }, - "example": { - "enabled": true, - "url": "url", - "max_score": 5 - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_spam_check" - }, - "examples": { - "application/json": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" } } } @@ -11653,35 +10920,27 @@ "Authorization": [] } ] - } - }, - "/mail_settings/template": { - "get": { - "operationId": "GET_mail_settings-template", - "summary": "Retrieve legacy template mail settings", + }, + "delete": { + "operationId": "DELETE_whitelabel-domains-subuser", + "summary": "Disassociate a authenticated domain from a given user.", "tags": [ - "Settings - Mail" - ], - "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).", - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to disassociate a specific authenticated domain from a subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate a authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The the parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "username", + "in": "query", + "description": "Username for the subuser to find associated authenticated domain.", + "type": "string" } ], "responses": { - "200": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_template" - }, - "examples": { - "application/json": { - "enabled": false, - "html_content": "

<% body %>Example

\n" - } + "type": "object" } } }, @@ -11690,20 +10949,25 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_mail_settings-template", - "summary": "Update template mail settings", + } + }, + "/whitelabel/domains/{domain_id}/subuser": { + "parameters": [ + { + "name": "domain_id", + "in": "path", + "description": "ID of the authenticated domain to associate with the subuser", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_whitelabel-domains-domain_id-subuser", + "summary": "Associate a authenticated domain with a given user.", "tags": [ - "Settings - Mail" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Domain Authentication" ], + "description": "**This endpoint allows you to associate a specific authenticated domain with a subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate a authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The the parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { "name": "body", @@ -11711,49 +10975,65 @@ "schema": { "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you want to enable the legacy email template mail setting." - }, - "html_content": { + "username": { "type": "string", - "description": "The new HTML content for your legacy email template." + "description": "Username to associate with the authenticated domain." } }, + "required": [ + "username" + ], "example": { - "enabled": true, - "html_content": "<% body %>" + "username": "jane@example.com" } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "201": { "description": "", "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the legacy email template mail setting is enabled." - }, - "html_content": { - "type": "string", - "description": "The HTML content of your legacy email template." - } - }, - "required": [ - "enabled", - "html_content" - ] + "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { - "enabled": false, - "html_content": "

<% body %>Example

\n" + "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 + } + } } } } @@ -11765,35 +11045,70 @@ ] } }, - "/mail_settings/bounce_purge": { + "/verified_senders/domains": { "get": { - "operationId": "GET_mail_settings-bounce_purge", - "summary": "Retrieve bounce purge mail settings", + "operationId": "GET_verified_senders-domains", + "summary": "Domain Warn List", "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Sender Verification" ], + "description": "**This endpoint returns a list of domains known to implement DMARC and categorizes them by failure type — hard failure or soft failure**.\n\nDomains listed as hard failures will not deliver mail when used as a [Sender Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) due to the domain's DMARC policy settings.\n\nFor example, using a `yahoo.com` email address as a Sender Identity will likely result in the rejection of your mail. For more information about DMARC, see [Everything about DMARC](https://sendgrid.com/docs/ui/sending-email/dmarc/).", "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" + "type": "object", + "properties": { + "results": { + "type": "object", + "required": [ + "soft_failures", + "hard_failures" + ], + "properties": { + "soft_failures": { + "type": "array", + "items": { + "type": "string" + } + }, + "hard_failures": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + }, + "required": [ + "results" + ] }, "examples": { "application/json": { - "enabled": false, - "soft_bounces": 1234, - "hard_bounces": null + "results": { + "soft_failures": [ + "gmail.com" + ], + "hard_failures": [ + "yahoo.com" + ] + } } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -11801,50 +11116,55 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_mail_settings-bounce_purge", - "summary": "Update bounce purge mail settings", + } + }, + "/verified_senders/steps_completed": { + "get": { + "operationId": "GET_verified_senders-steps_completed", + "summary": "Completed Steps", "tags": [ - "Settings - Mail" - ], - "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’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).", - "consumes": [ - "application/json" + "Sender Verification" ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", + "description": "**This endpoint allows you to determine which of SendGrid’s verification processes have been completed for an account**.\n\nThis endpoint returns boolean values, `true` and `false`, for [Domain Authentication](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#domain-authentication), `domain_verified`, and [Single Sender Verification](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#single-sender-verification), `sender_verified`, for the account.\n\nAn account may have one, both, or neither verification steps completed. If you need to authenticate a domain rather than a Single Sender, see the \"#endpoint:aXpkWYramCg4ZNEGT\" endpoint.", + "responses": { + "200": { + "description": "", "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge", - "example": { - "enabled": true, - "hard_bounces": 5, - "soft_bounces": 5 + "type": "object", + "properties": { + "results": { + "type": "object", + "properties": { + "sender_verified": { + "type": "boolean" + }, + "domain_verified": { + "type": "boolean" + } + } + } } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/mail_settings_bounce_purge" }, "examples": { "application/json": { - "enabled": false, - "hard_bounces": null, - "soft_bounces": null + "results": { + "domain_verified": true, + "sender_verified": true + } } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -11854,34 +11174,91 @@ ] } }, - "/mail_settings/forward_bounce": { - "get": { - "operationId": "GET_mail_settings-forward_bounce", - "summary": "Retrieve forward bounce mail settings", + "/verified_senders": { + "post": { + "operationId": "POST_verified_senders", + "summary": "Create Verified Sender Request", "tags": [ - "Settings - Mail" - ], - "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’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).", - "produces": [ - "application/json" + "Sender Verification" ], + "description": "**This endpoint allows you to create a new Sender Identify**.\n\nUpon successful submission of a `POST` request to this endpoint, an identity will be created, and a verification email will be sent to the address assigned to the `from_email` field. You must complete the verification process using the sent email to fully verify the sender.\n\nIf you need to resend the verification email, you can do so with the Resend Verified Sender Request, `/resend/{id}`, endpoint.\n\nIf you need to authenticate a domain rather than a Single Sender, see the [Domain Authentication API](https://sendgrid.api-docs.io/v3.0/domain-authentication/authenticate-a-domain).", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/verified-sender-request-schema" + } } ], "responses": { - "200": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_forward_bounce" + "$ref": "#/definitions/verified-sender-response-schema" }, "examples": { "application/json": { - "enabled": false, - "email": null + "id": 1234, + "nickname": "Example Orders", + "from_email": "orders@example.com", + "from_name": "Example Orders", + "reply_to": "orders@example.com", + "reply_to_name": "Example Orders", + "address": "1234 Fake St.", + "address2": "PO Box 1234", + "state": "CA", + "city": "San Francisco", + "country": "USA", + "zip": "94105", + "verified": true, + "locked": false } } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + }, + "required": [ + "message", + "error_id" + ] + } + } + }, + "required": [ + "errors" + ] + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -11890,47 +11267,94 @@ } ] }, - "patch": { - "operationId": "PATCH_mail_settings-forward_bounce", - "summary": "Update forward bounce mail settings", + "get": { + "operationId": "GET_verified_senders", + "summary": "Get All Verified Senders", "tags": [ - "Settings - Mail" - ], - "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’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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Sender Verification" ], + "description": "**This endpoint allows you to retrieve all the Sender Identities associated with an account.**\n\nThis endpoint will return both verified and unverified senders.\n\nYou can limit the number of results returned using the `limit`, `lastSeenID`, and `id` query string parameters.\n\n* `limit` allows you to specify an exact number of Sender Identities to return.\n* `lastSeenID` will return senders with an ID number occuring after the passed in ID. In other words, the `lastSeenID` provides a starting point from which SendGrid will iterate to find Sender Identities associated with your account.\n* `id` will return information about only the Sender Identity passed in the request.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "$ref": "#/definitions/mail_settings_forward_bounce", - "example": { - "enabled": true, - "email": "example@example.com" - } - } + "name": "limit", + "in": "query", + "type": "number" }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "lastSeenID", + "in": "query", + "type": "number" + }, + { + "name": "id", + "in": "query", + "type": "integer" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/mail_settings_forward_bounce" + "type": "object", + "properties": { + "results": { + "type": "array", + "items": { + "$ref": "#/definitions/verified-sender-response-schema" + } + } + } }, "examples": { "application/json": { - "email": "", - "enabled": true + "results": [ + { + "id": 1234, + "nickname": "Example Orders", + "from_email": "orders@example.com", + "from_name": "Example Orders", + "reply_to": "orders@example.com", + "reply_to_name": "Example Orders", + "address": "1234 Fake St.", + "address2": "PO Box 1234", + "state": "CA", + "city": "San Francisco", + "country": "USA", + "zip": "94105", + "verified": true, + "locked": false + }, + { + "id": 1235, + "nickname": "Example Support", + "from_email": "support@example.com", + "from_name": "Example Support", + "reply_to": "support@example.com", + "reply_to_name": "Example Support", + "address": "1234 Fake St.", + "address2": "PO Box 1234", + "state": "CA", + "city": "San Francisco", + "country": "USA", + "zip": "94105", + "verified": true, + "locked": false + } + ] } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -11940,81 +11364,63 @@ ] } }, - "/partner_settings": { + "/verified_senders/verify/{token}": { + "parameters": [ + { + "name": "token", + "in": "path", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_partner_settings", - "summary": "Returns a list of all partner settings.", + "operationId": "GET_verified_senders-verify-token", + "summary": "Verify Sender Request", "tags": [ - "Settings - Partner" - ], - "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).", - "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" - } + "Sender Verification" ], + "description": "**This endpoint allows you to verify a sender requests.**\n\nThe token is generated by SendGrid and included in a verification email delivered to the address that's pending verification.", "responses": { - "200": { + "204": { + "description": "" + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { "description": "", "schema": { "type": "object", "properties": { - "result": { + "errors": { "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." + "message": { + "type": "string" }, - "description": { - "type": "string", - "description": "A description of this partner setting." + "error_id": { + "type": "string" } }, "required": [ - "title", - "enabled", - "name", - "description" + "message", + "error_id" ] } } - } - }, - "examples": { - "application/json": { - "result": [ - { - "title": "Partner title", - "enabled": true, - "name": "partner_name", - "description": "A description of a partner." - } - ] - } + }, + "required": [ + "errors" + ] } + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -12024,92 +11430,151 @@ ] } }, - "/partner_settings/new_relic": { - "get": { - "operationId": "GET_partner_settings-new_relic", - "summary": "Returns all New Relic partner settings.", + "/verified_senders/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "patch": { + "operationId": "PATCH_verified_senders-id", + "summary": "Edit Verified Sender", "tags": [ - "Settings - Partner" + "Sender Verification" ], - "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).", - "produces": [ - "application/json" + "description": "**This endpoint allows you to update an existing Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint as a path parameter. Include any fields you wish to update in the request body in JSON format.\n\nYou can retrieve the IDs associated with Sender Identities by passing a `GET` request to the Get All Verified Senders endpoint, `/verified_senders`.\n\n**Note:** Unlike a `PUT` request, `PATCH` allows you to update only the fields you wish to edit. Fields that are not passed as part of a request will remain unaltered.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/verified-sender-request-schema" + } + } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/partner_settings_new_relic" + "$ref": "#/definitions/verified-sender-response-schema" }, "examples": { "application/json": { - "enable_subuser_statistics": false, - "enabled": true, - "license_key": "" + "id": 1234, + "nickname": "Example Orders", + "from_email": "orders@example.com", + "from_name": "Example Orders", + "reply_to": "orders@example.com", + "reply_to_name": "Example Orders", + "address": "1234 Fake St.", + "address2": "PO Box 1234", + "state": "CA", + "city": "San Francisco", + "country": "USA", + "zip": "94105", + "verified": true, + "locked": false } } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "operationId": "PATCH_partner_settings-new_relic", - "summary": "Updates New Relic partner settings.", - "tags": [ - "Settings - Partner" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", + }, + "400": { + "description": "", "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." + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + }, + "required": [ + "message", + "error_id" + ] + } } }, - "example": { - "license_key": "", - "enabled": true, - "enable_subuser_statistics": true - } + "required": [ + "errors" + ] } - } - ], - "responses": { - "200": { + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { "description": "", "schema": { - "$ref": "#/definitions/partner_settings_new_relic" - }, - "examples": { - "application/json": { - "enable_subuser_statistics": true, - "enabled": true, - "license_key": "" - } + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + }, + "required": [ + "message", + "error_id" + ] + } + } + }, + "required": [ + "errors" + ] + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + }, + "required": [ + "message", + "error_id" + ] + } + } + }, + "required": [ + "errors" + ] } + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -12117,81 +11582,81 @@ "Authorization": [] } ] - } - }, - "/tracking_settings": { - "get": { - "operationId": "GET_tracking_settings", - "summary": "Retrieve Tracking Settings", + }, + "delete": { + "operationId": "DELETE_verified_senders-id", + "summary": "Delete Verified Sender", "tags": [ - "Settings - Tracking" - ], - "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).", - "produces": [ - "application/json" + "Sender Verification" ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of settings to return.", - "type": "integer" + "description": "**This endpoint allows you to delete a Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint to delete the Sender Identity from your account.\n\nYou can retrieve the IDs associated with Sender Identities using the #endpoint:ow3obGPTZxwZAJtkn endpoint.", + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" + } }, - { - "name": "offset", - "in": "query", - "description": "Where in the list of results you want to begin retrieving settings.", - "type": "integer" + "401": { + "$ref": "#/responses/trait:globalErrors:401" }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { + "403": { "description": "", "schema": { "type": "object", "properties": { - "result": { + "errors": { "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." + "message": { + "type": "string" }, - "enabled": { - "type": "boolean", - "description": "Indicates if this tracking setting is currently enabled." + "error_id": { + "type": "string" } - } + }, + "required": [ + "message", + "error_id" + ] } } } - }, - "examples": { - "application/json": { - "result": [ - { - "name": "open", - "title": "Open Tracking", - "description": "lorem ipsum... .", - "enabled": true + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + }, + "required": [ + "message", + "error_id" + ] } - ] - } + } + }, + "required": [ + "errors" + ] } + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -12201,48 +11666,95 @@ ] } }, - "/tracking_settings/click": { - "get": { - "operationId": "GET_tracking_settings-click", - "summary": "Retrieve Click Track Settings", + "/verified_senders/resend/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "post": { + "operationId": "POST_verified_senders-resend-id", + "summary": "Resend Verified Sender Request", "tags": [ - "Settings - Tracking" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Sender Verification" ], + "description": "**This endpoint allows you to resend a verification email to a specified Sender Identity**.\n\nPassing the `id` assigned to a Sender Identity to this endpoint will resend a verification email to the `from_address` associated with the Sender Identity. This can be useful if someone loses their verification email or needs to have it resent for any other reason.\n\nYou can retrieve the IDs associated with Sender Identities by passing a \"#endpoint:ow3obGPTZxwZAJtkn\" endpoint.", "responses": { - "200": { + "204": { "description": "", "schema": { - "type": "object", - "properties": { - "enable_text": { - "type": "boolean", - "description": "Indicates if click tracking is enabled for plain text emails." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if click tracking is enabled or disabled." + "type": "object" + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + }, + "required": [ + "message", + "error_id" + ] + } } }, "required": [ - "enable_text", - "enabled" + "errors" ] - }, - "examples": { - "application/json": { - "enable_text": false, - "enabled": true - } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + }, + "required": [ + "message", + "error_id" + ] + } + } + }, + "required": [ + "errors" + ] + } + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -12250,67 +11762,59 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_tracking_settings-click", - "summary": "Update Click Tracking Settings", + } + }, + "/designs": { + "post": { + "operationId": "POST-design", + "summary": "Create Design", "tags": [ - "Settings - Tracking" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Designs API" ], + "description": "**This endpoint allows you to create a new design**.\n\nYou can add a new design by passing data, including a string of HTML email content, to `/designs`. When creating designs from scratch, be aware of the styling constraints inherent to many email clients. For a list of best practices, see our guide to [Cross-Platform Email Design](https://sendgrid.com/docs/ui/sending-email/cross-platform-html-design/).\n\nThe Design Library can also convert your design’s HTML elements into drag and drop modules that are editable in the Designs Library user interface. For more, visit the [Design and Code Editor documentation](https://sendgrid.com/docs/ui/sending-email/editor/#drag--drop-markup).\n\nBecause the `/designs` endpoint makes it easy to add designs, you can create a design with your preferred tooling or migrate designs you already own without relying on the Design Library UI.", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "The setting you want to use for click tracking." - } - }, + "$ref": "#/definitions/design-input", "example": { - "enabled": true + "name": "Ahoy, World!", + "editor": "design", + "subject": "Getting Started", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )" } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "201": { "description": "", "schema": { - "type": "object", - "properties": { - "enable_text": { - "type": "boolean", - "description": "Indicates if click tracking is enabled for plain text emails" - }, - "enabled": { - "type": "boolean", - "description": "The new setting new setting for click tracking." - } - }, - "required": [ - "enable_text", - "enabled" - ] + "$ref": "#/definitions/design-output" }, "examples": { "application/json": { - "enable_text": false, - "enabled": true + "id": "3247eaea-c912-42a3-b0bc-60bdaf210396", + "name": "Ahoy, World!", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", + "generate_plain_content": false, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/kjlrmded0qnrscv8zqr39npoimrpdwgiax59q8iq6ovj7yoks2fzxoxpfjpwph6o.png", + "subject": "Getting Started", + "created_at": "2021-04-30T18:51:20Z", + "updated_at": "2021-04-30T18:51:20Z", + "editor": "design", + "categories": [] } } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } } }, "security": [ @@ -12318,38 +11822,89 @@ "Authorization": [] } ] - } - }, - "/tracking_settings/google_analytics": { + }, "get": { - "operationId": "GET_tracking_settings-google_analytics", - "summary": "Retrieve Google Analytics Settings", + "operationId": "LIST-designs", + "summary": "List Designs", "tags": [ - "Settings - Tracking" - ], - "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’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).\n\nWe 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).\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).", - "produces": [ - "application/json" + "Designs API" ], + "description": "**This endpoint allows you to retrieve a list of designs already stored in your Design Library**.\n\nA GET request to `/designs` will return a list of your existing designs. This endpoint will not return the pre-built Twilio SendGrid designs. Pre-built designs can be retrieved using the `/designs/pre-builts` endpoint, which is detailed below.\n\nBy default, you will receive 100 results per request; however, you can modify the number of results returned by passing an integer to the `page_size` query parameter.", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "$ref": "#/parameters/trait:designsQueryStrings:page_size" + }, + { + "$ref": "#/parameters/trait:designsQueryStrings:page_token" + }, + { + "$ref": "#/parameters/trait:designsQueryStrings:summary" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/google_analytics_settings" + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/design-output-summary" + } + }, + "_metadata": { + "$ref": "#/definitions/_metadata" + } + } }, "examples": { "application/json": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" + "result": [ + { + "id": "3247eaea-c912-42a3-b0bc-60bdaf210396", + "name": "Welcome Email", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/llny8o5b3m636z92p7hbjnmq1jvpka39p370jwtin2s1wxv7x1sgm0y5fk518d0s.png", + "subject": "Welcom to the Cake or Pie Cafe", + "created_at": "2021-04-09T17:29:46Z", + "updated_at": "2021-04-09T17:29:55Z", + "editor": "code", + "categories": [ + "welcome", + "new customer" + ] + }, + { + "id": "02dfd792-f31f-439a-a79e-5c47fbcfdbac", + "name": "Monthly Promo", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/hfyxahd7ues2ajuoeoqq2xe6ibdasl1q89ox0y9ncya2ftpoicssmtf9ddus4c39.png", + "subject": "Free Dozen Cupcakes", + "created_at": "2021-04-09T17:29:21Z", + "updated_at": "2021-04-09T17:29:42Z", + "editor": "design", + "categories": [ + "promo", + "coupon" + ] + }, + { + "id": "e54be823-19ef-4c6f-8b60-efd7514f492d", + "name": "Duplicate: Ingrid & Anders", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/12kni9gjpyb9uxmwr9vk7unycjr70u95zoyhe9sg2zounul2zg7dih1s20k13q2z.png", + "subject": "Welcome to Ingrid & Anders!", + "created_at": "2020-10-09T17:33:46Z", + "updated_at": "2021-04-07T19:57:52Z", + "editor": "design", + "categories": [] + } + ], + "_metadata": { + "self": "https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I", + "count": 3 + } } } } @@ -12359,56 +11914,72 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_tracking_settings-google_analytics", - "summary": "Update Google Analytics Settings", + } + }, + "/designs/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The ID of the Design you want to duplicate.", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "post": { + "operationId": "POST-design", + "summary": "Duplicate Design", "tags": [ - "Settings - Tracking" - ], - "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’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).\n\nWe 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).\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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Designs API" ], + "description": "**This endpoint allows you to duplicate one of your existing designs**.\n\nModifying an existing design is often the easiest way to create something new.\n\nYou are not required to pass any data in the body of a request to this endpoint. If you choose to leave the `name` field blank, your duplicate will be assigned the name of the design it was copied from with the text \"Duplicate: \" prepended to it. This name change is only a convenience, as the duplicate will be assigned a unique ID that differentiates it from your other designs.\n\nYou can modify your duplicate’s name at the time of creation by passing an updated value to the `name` field when making the initial request.\nMore on retrieving design IDs can be found below.", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/google_analytics_settings", + "$ref": "#/definitions/design-duplicate-input", "example": { - "enabled": true, - "utm_source": "sendgrid.com", - "utm_medium": "email", - "utm_term": "", - "utm_content": "", - "utm_campaign": "website" + "name": "Ahoy, Cake or Pie Cafe!", + "editor": "design" } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/google_analytics_settings" + "$ref": "#/definitions/design-output" }, "examples": { "application/json": { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" + "id": "15b85720-ce48-48ef-8a07-672b0d3455da", + "name": "Ahoy, Cake or Pie Cafe!", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", + "generate_plain_content": false, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/79bb769ae6464960a307040120ad6f9921896fe9825e845ad1f24d12285ea068.png", + "subject": "Getting Started", + "created_at": "2021-04-30T19:00:16Z", + "updated_at": "2021-04-30T19:00:16Z", + "editor": "design", + "categories": [] } } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/api-error" + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } } }, "security": [ @@ -12416,44 +11987,47 @@ "Authorization": [] } ] - } - }, - "/tracking_settings/open": { + }, "get": { - "operationId": "GET_tracking_settings-open", - "summary": "Get Open Tracking Settings", + "operationId": "GET-design", + "summary": "Get Design", "tags": [ - "Settings - Tracking" - ], - "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’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.\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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Designs API" ], + "description": "**This endpoint allows you to retrieve a single design**.\n\nA GET request to `/designs/{id}` will retrieve details about a specific design in your Design Library.\n\nThis endpoint is valuable when retrieving information stored in a field that you wish to update using a PATCH request.", "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if open tracking is enabled." - } - }, - "required": [ - "enabled" - ] + "$ref": "#/definitions/design-output" }, "examples": { "application/json": { - "enabled": true + "id": "15b85720-ce48-48ef-8a07-672b0d3455da", + "name": "Ahoy, World!", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", + "generate_plain_content": false, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/5yysvuyi1lpdnxo1ym8ax8yd7ompve3azjtme76gamdace01vko3eyn1kzso1lhy.png", + "subject": "Getting Started", + "created_at": "2021-04-30T18:51:20Z", + "updated_at": "2021-04-30T18:51:20Z", + "editor": "design", + "categories": [] } } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } } }, "security": [ @@ -12463,18 +12037,12 @@ ] }, "patch": { - "operationId": "PATCH_tracking_settings-open", - "summary": "Update Open Tracking Settings", + "operationId": "PUT-design", + "summary": "Update Design", "tags": [ - "Settings - Tracking" - ], - "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’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.\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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Designs API" ], + "description": "**This endpoint allows you to edit a design**.\n\nThe Design API supports PATCH requests, which allow you to make partial updates to a single design. Passing data to a specific field will update only the data stored in that field; all other fields will be unaltered.\n\nFor example, updating a design's name requires that you make a PATCH request to this endpoint with data specified for the `name` field only.\n\n```\n{\n \"name\": \"\"\n}\n```", "parameters": [ { "name": "body", @@ -12482,40 +12050,90 @@ "schema": { "type": "object", "properties": { - "enabled": { + "name": { + "type": "string", + "description": "Name of the Design.", + "maxLength": 100, + "default": "My Design" + }, + "html_content": { + "type": "string", + "description": "The HTML content of the Design.", + "maxLength": 1048576 + }, + "plain_content": { + "type": "string", + "description": "Plain text content of the Design.", + "maxLength": 1048576, + "default": "" + }, + "generate_plain_content": { "type": "boolean", - "description": "The new status that you want to set for open tracking." - } + "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", + "default": true + }, + "subject": { + "type": "string", + "description": "Subject of the Design.", + "maxLength": 5000 + }, + "categories": { + "type": "array", + "description": "The list of categories applied to the design", + "uniqueItems": true, + "maxItems": 10, + "items": { + "type": "string", + "maxLength": 255 + } + } }, "example": { - "enabled": true + "name": "Ahoy, World!", + "subject": "Getting Started", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "generate_plain_content": false, + "categories": [ + "promotions" + ] } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if open tracking is enabled." - } - }, - "required": [ - "enabled" - ] + "$ref": "#/definitions/design-output" }, "examples": { "application/json": { - "enabled": true + "id": "15b85720-ce48-48ef-8a07-672b0d3455da", + "name": "Ahoy, World!", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "generate_plain_content": false, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/5yysvuyi1lpdnxo1ym8ax8yd7ompve3azjtme76gamdace01vko3eyn1kzso1lhy.png", + "subject": "Getting Started", + "created_at": "2021-04-30T18:51:20Z", + "updated_at": "2021-04-30T18:51:20Z", + "editor": "design", + "categories": [ + "promotions" + ] } } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } } }, "security": [ @@ -12523,39 +12141,31 @@ "Authorization": [] } ] - } - }, - "/tracking_settings/subscription": { - "get": { - "operationId": "GET_tracking_settings-subscription", - "summary": "Retrieve Subscription Tracking Settings", + }, + "delete": { + "operationId": "DELETE-design", + "summary": "Delete Design", "tags": [ - "Settings - Tracking" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "Designs API" ], + "description": "**This endpoint allows you to delete a single design**.\n\nBe sure to check the ID of the design you intend to delete before making this request; deleting a design is a permanent action.", "responses": { - "200": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/subscription_tracking_settings" - }, - "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": "" - } + "type": "object" + } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" } } }, @@ -12564,56 +12174,120 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_tracking_settings-subscription", - "summary": "Update Subscription Tracking Settings", + } + }, + "/designs/pre-builts/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The ID of the pre-built Design you want to duplicate.", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "post": { + "operationId": "POST-sendgrid-pre-built-design", + "summary": "Duplicate SendGrid Pre-built Design", "tags": [ - "Settings - Tracking" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Designs API" ], + "description": "**This endpoint allows you to duplicate one of the pre-built Twilio SendGrid designs**.\n\nLike duplicating one of your existing designs, you are not required to pass any data in the body of a request to this endpoint. If you choose to leave the `name` field blank, your duplicate will be assigned the name of the design it was copied from with the text \"Duplicate: \" prepended to it. This name change is only a convenience, as the duplicate design will be assigned a unique ID that differentiates it from your other designs. You can retrieve the IDs for Twilio SendGrid pre-built designs using the #endpoint:onypXY6DEQabeqdF7 endpoint.\n\nYou can modify your duplicate’s name at the time of creation by passing an updated value to the `name` field when making the initial request.\nMore on retrieving design IDs can be found above.", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/subscription_tracking_settings", + "$ref": "#/definitions/design-duplicate-input", "example": { - "enabled": true, - "landing": "landing page html", - "url": "url", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" + "name": "Ahoy, Cake or Pie Cafe!", + "editor": "design" + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/design-output" + }, + "examples": { + "application/json": { + "id": "abe0877f-a224-21e2-b62e-c789d326cda5", + "name": "Ahoy, Pre-built Design!", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

You've found the secret!

\n
\n \n \n \n
\"Off
\n \n \n \n
\"\"
\n \n \n \n
Welcome to the family!
\n \n \n \n
You've found a community of travelers that are just like you.
\n
 
\n
We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.
\n
 
\n
Ready for your next authentic travel experience?
Browse Gallery
\n \n \n \n
\"\"
\n \n \n \n
\n
\n \n \n \n
\n \n \n \n \n
\n
\n \n \n \n
\n
\n \n \n \n \n \n
\n \n \n
\n \n \"Facebook\"\n \n \n \n \"Twitter\"\n \n \n \n \"Instagram\"\n \n \n \n \"Pinterest\"\n \n
\n

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "plain_content": "You've found the secret!\n\nWelcome to the family!\n\nYou've found a community of travelers that are just like you.\n\nWe don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.\n\nReady for your next authentic travel experience?\n\nBrowse Gallery\n\n( https://www.facebook.com/sendgrid/ ) ( https://twitter.com/sendgrid?ref_src=twsrc%5egoogle%7ctwcamp%5eserp%7ctwgr%5eauthor ) ( https://www.instagram.com/sendgrid/?hl=en ) ( https://www.pinterest.com/sendgrid/ )\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png", + "subject": "Welcome to the family!", + "created_at": "2021-04-30T19:15:28Z", + "updated_at": "2021-04-30T19:15:28Z", + "editor": "design", + "categories": [] } } }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } + } + }, + "security": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "Authorization": [] } + ] + }, + "get": { + "operationId": "GET-sendgrid-pre-built-design", + "summary": "Get SendGrid Pre-built Design", + "tags": [ + "Designs API" ], + "description": "**This endpoint allows you to retrieve a single pre-built design**.\n\nA GET request to `/designs/pre-builts/{id}` will retrieve details about a specific pre-built design.\n\nThis endpoint is valuable when retrieving details about a pre-built design that you wish to duplicate and modify.", "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/subscription_tracking_settings" + "$ref": "#/definitions/design-output" }, "examples": { "application/json": { - "enabled": true, - "landing": "landing page html", - "url": "url", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" + "id": "6ad69134-7165-48cb-964a-6c3cf03e8af8", + "name": "Off Grid Adventures", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n\n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

You've found the secret!

\n
\n \n \n \n
\"Off
\n \n \n \n
\"\"
\n \n \n \n
Welcome to the family!
\n \n \n \n
You've found a community of travelers that are just like you.
\n
 
\n
We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.
\n
 
\n
Ready for your next authentic travel experience?
Browse Gallery
\n \n \n \n
\"\"
\n \n \n \n
\n
\n \n \n \n
\n \n \n \n \n
\n
\n \n \n \n
\n
\n \n \n \n \n \n
\n \n \n
\n \n \"Facebook\"\n \n \n \n \"Twitter\"\n \n \n \n \"Instagram\"\n \n \n \n \"Pinterest\"\n \n
\n

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "plain_content": "You've found the secret!\n\nWelcome to the family!\n\nYou've found a community of travelers that are just like you.\n\nWe don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.\n\nReady for your next authentic travel experience?\n\nBrowse Gallery\n\n( https://www.facebook.com/sendgrid/ ) ( https://twitter.com/sendgrid?ref_src=twsrc%5egoogle%7ctwcamp%5eserp%7ctwgr%5eauthor ) ( https://www.instagram.com/sendgrid/?hl=en ) ( https://www.pinterest.com/sendgrid/ )\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png", + "subject": "Welcome to the family!", + "created_at": "2019-09-10T02:11:34Z", + "updated_at": "2021-01-11T21:47:52Z", + "editor": "design", + "categories": [] } } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/api-errors" + } } }, "security": [ @@ -12623,87 +12297,117 @@ ] } }, - "/suppression/spam_reports": { + "/designs/pre-builts": { "get": { - "operationId": "GET_suppression-spam_reports", - "summary": "Retrieve all spam reports", + "operationId": "LIST-Sendgrid-Pre-built-designs", + "summary": "List SendGrid Pre-built Designs", "tags": [ - "Spam Reports API" - ], - "description": "**This endpoint allows you to retrieve all spam reports.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", - "produces": [ - "application/json" + "Designs API" ], + "description": "**This endpoint allows you to retrieve a list of pre-built designs provided by Twilio SendGrid**.\n\nUnlike the `/designs` endpoint where *your* designs are stored, a GET request made to `designs/pre-builts` will retrieve a list of the pre-built Twilio SendGrid designs. This endpoint will not return the designs stored in your Design Library.\n\nBy default, you will receive 100 results per request; however, you can modify the number of results returned by passing an integer to the `page_size` query parameter.\n\nThis endpoint is useful for retrieving the IDs of Twilio SendGrid designs that you want to duplicate and modify.", "parameters": [ { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when a spam report was created (inclusive).", - "type": "integer" - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when a spam report was created (inclusive).", - "type": "integer" - }, - { - "name": "limit", - "in": "query", - "description": "Limit the number of results to be displayed per page.", - "type": "integer" + "$ref": "#/parameters/trait:designsQueryStrings:page_size" }, { - "name": "offset", - "in": "query", - "description": "Paging offset. The point in the list to begin displaying results.", - "type": "integer" + "$ref": "#/parameters/trait:designsQueryStrings:page_token" }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "$ref": "#/parameters/trait:designsQueryStrings:summary" } ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the spam report was made." - }, - "email": { - "type": "string", - "description": "The email address of the recipient who marked your message as spam." - }, - "ip": { - "type": "string", - "description": "The IP address that the message was sent on." + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/design-output-summary" } }, - "required": [ - "created", - "email", - "ip" - ] + "_metadata": { + "$ref": "#/definitions/_metadata" + } } }, "examples": { - "application/json": [ - { - "created": 1443651141, - "email": "user1@example.com", - "ip": "10.63.202.100" - }, - { - "created": 1443651154, - "email": "user2@example.com", - "ip": "10.63.202.100" + "application/json": { + "result": [ + { + "id": "6ad69134-7165-48cb-964a-6c3cf03e8af8", + "name": "Off Grid Adventures", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png", + "subject": "Welcome to the family!", + "created_at": "2019-09-10T02:11:34Z", + "updated_at": "2021-01-11T21:47:52Z", + "editor": "design", + "categories": [] + }, + { + "id": "b0a9c6f7-a9a1-4b52-b0c5-16fc6f4cdb2b", + "name": "Song Riddle", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/4ef3a39249f3accb8461b03950c071454a745a232508feca89a626b3e7f578d3.png", + "subject": "Welcome to Song Riddle!", + "created_at": "2019-09-10T02:12:32Z", + "updated_at": "2021-01-11T21:46:43Z", + "editor": "design", + "categories": [] + }, + { + "id": "f8d8da76-bcca-4cfe-b809-733887855f57", + "name": "Ingrid & Anders 1", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/15c97ffa97ee31693581a67526728d096eef00adfbaa34bb030d91034d477da4.png", + "subject": "Welcome to Ingrid & Anders!", + "created_at": "2019-09-10T02:10:38Z", + "updated_at": "2021-01-11T21:45:05Z", + "editor": "design", + "categories": [] + }, + { + "id": "2935a7d0-7f02-4e0f-a570-dc302ce09749", + "name": "Ingrid & Anders 2", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/7b36a6c0955cab0c350d105114ad248700a685bd11032592cdef85ae26540afc.png", + "subject": "Check out these exclusive deals!", + "created_at": "2019-09-10T02:09:31Z", + "updated_at": "2021-01-11T21:44:08Z", + "editor": "design", + "categories": [] + }, + { + "id": "7826ef14-7ba6-4dbc-91f0-a8c610ebe962", + "name": "Ingrid & Anders 3", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/6dd8dd73a1a62bd7a76c4313b52d7c749250d49e31b19cce718906655fcbc675.png", + "subject": "Join our VIP club and save big!", + "created_at": "2019-09-10T02:08:29Z", + "updated_at": "2021-01-11T21:41:35Z", + "editor": "design", + "categories": [] + }, + { + "id": "41da47e7-d3e2-491b-a83f-f499a4139d6a", + "name": "Mercado", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/9cc87cc7671719712d9d363184995d0ec05103355db300ff03641fe9e205651d.png", + "subject": "Subject", + "created_at": "2019-09-10T02:03:06Z", + "updated_at": "2021-01-11T21:39:23Z", + "editor": "design", + "categories": [] + } + ], + "_metadata": { + "self": "https://api.sendgrid.com/v3/designs/pre-builts?page_token=yYzyCxj-iIVgP54t6NjKkunDCKYLLpngo-5vAsfYXz0To34U", + "count": 6 } - ] + } } } }, @@ -12712,17 +12416,16 @@ "Authorization": [] } ] - }, - "delete": { - "operationId": "DELETE_suppression-spam_reports", - "summary": "Delete spam reports", + } + }, + "/marketing/contacts": { + "put": { + "operationId": "PUT_mc-contacts", + "summary": "Add or Update a Contact", "tags": [ - "Spam Reports API" - ], - "description": "**This endpoint allows you to delete your spam reports.**\n\nThere are two options for deleting spam reports: \n\n1) You can delete all spam reports by setting \"delete_all\" to true in the request body. \n2) You can delete some spam reports by specifying the email addresses in an array in the request body.\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", - "produces": [ - "application/json" + "Contacts" ], + "description": "**This endpoint allows the [upsert](https://en.wiktionary.org/wiki/upsert) (insert or update) of up to 30,000 contacts, or 6MB of data, whichever is lower**. \n\nBecause the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to confirm your contacts have been updated or added, you can use the #endpoint:oNz2fgJriXmSkdyEe endpoint.\n\nPlease note that custom fields need to have been already created if you wish to set their values for the contacts being upserted. To do this, please use the #endpoint:oC6DjiarRqXQu5kTm endpoint.\n\nYou will see a `job_id` in the response to your request. This can be used to check the status of your upsert job. To do so, please use the #endpoint:m5WnoiseMvTXuNwZt endpoint.\n\nThe email field is case sensitive. If you add an email with capital letters then try to use the #endpoint:oNz2fgJriXmSkdyEe endpoint, you will need to apply the same case you used when updating or adding the contact.\n\nIf the contact already exists in the system, any entries you submit via this endpoint will update the existing contact.", "parameters": [ { "name": "body", @@ -12730,38 +12433,68 @@ "schema": { "type": "object", "properties": { - "delete_all": { - "type": "boolean", - "description": "Indicates if you want to delete all email addresses on the spam report list." + "list_ids": { + "type": "array", + "description": "An array of List ID strings that this contact will be added to.", + "items": { + "type": "string", + "format": "uuid" + } }, - "emails": { + "contacts": { "type": "array", - "description": "A list of specific email addresses that you want to remove from the spam report list.", + "description": "One or more contacts objects that you intend to upsert. The available fields for a contact, including the required `email` field are described below.", + "minItems": 1, + "maxItems": 30000, "items": { - "type": "string" + "$ref": "#/definitions/contact-request" } } }, - "example": { - "delete_all": false, - "emails": [ - "example1@example.com", - "example2@example.com" - ] - } + "required": [ + "contacts" + ] } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { + "202": { "description": "", "schema": { "type": "object", - "properties": {} + "properties": { + "job_id": { + "type": "string", + "description": "Indicates that the contacts are queued for processing. Check the job status with the #endpoint:m5WnoiseMvTXuNwZt endpoint." + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/definitions/error" + } + } + } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -12769,70 +12502,75 @@ "Authorization": [] } ] - } - }, - "/suppression/spam_reports/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address of a specific spam report that you want to retrieve.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_suppression-spam_reports-email", - "summary": "Retrieve a specific spam report", + }, + "delete": { + "operationId": "DELETE_mc-contacts", + "summary": "Delete Contacts", "tags": [ - "Spam Reports API" - ], - "description": "**This endpoint allows you to retrieve a specific spam report.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", - "produces": [ - "application/json" + "Contacts" ], + "description": "**This endpoint can be used to delete one or more contacts**.\n\nThe query parameter `ids` must set to a comma-separated list of contact IDs for bulk contact deletion.\n\nThe query parameter `delete_all_contacts` must be set to `\"true\"` to delete **all** contacts. \n\nYou must set either `ids` or `delete_all_contacts`.\n\nDeletion jobs are processed asynchronously.", "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "delete_all_contacts", + "in": "query", + "description": "Must be set to `\"true\"` to delete all contacts.", + "required": false, + "type": "string" + }, + { + "name": "ids", + "in": "query", + "description": "A comma-separated list of contact IDs.", + "required": false, + "type": "string" } ], "responses": { - "200": { + "202": { "description": "", "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp that indicates when the recipient marked your message as spam." - }, - "email": { - "type": "string", - "description": "The email address of the recipient that marked your message as spam." - }, - "ip": { - "type": "string", - "description": "The IP address that the message was sent from." + "type": "object", + "description": "The deletion job has been accepted and is being processed.", + "properties": { + "job_id": { + "type": "object", + "description": "The deletion job ID." + } + }, + "required": [ + "job_id" + ] + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object" } - }, - "required": [ - "created", - "email", - "ip" - ] - } - }, - "examples": { - "application/json": [ - { - "created": 1454433146, - "email": "test1@example.com", - "ip": "10.89.32.5" } + }, + "required": [ + "errors" ] } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -12841,32 +12579,62 @@ } ] }, - "delete": { - "operationId": "DELETE_suppression-spam_reports-email", - "summary": "Delete a specific spam report", + "get": { + "operationId": "GET_mc-contats", + "summary": "Get Sample Contacts", "tags": [ - "Spam Reports API" + "Contacts" ], - "description": "**This endpoint allows you to delete a specific spam report.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", - "parameters": [ - { - "name": "body", - "in": "body", + "description": "**This endpoint will return up to 50 of the most recent contacts uploaded or attached to a list**. \n\nThis list will then be sorted by email address.\n\nThe full contact count is also returned.\n\nPlease note that pagination of the contacts has been deprecated.", + "responses": { + "200": { + "description": "", "schema": { - "type": "null" + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/contact-details3" + } + }, + "_metadata": { + "$ref": "#/definitions/selfmetadata" + }, + "contact_count": { + "type": "integer" + } + } } }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { + "400": { "description": "", "schema": { "type": "object", - "properties": {} + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/definitions/error" + } + } + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "type": "object" } + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -12876,338 +12644,335 @@ ] } }, - "/stats": { + "/marketing/contacts/count": { "get": { - "operationId": "GET_stats", - "summary": "Retrieve global email statistics", + "operationId": "GET_mc-contacts-count", + "summary": "Get Total Contact Count", "tags": [ - "Stats" - ], - "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.", - "produces": [ - "application/json" + "Contacts" ], - "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" + "description": "**This endpoint returns the total number of contacts you have stored.**", + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "contact_count": { + "type": "integer", + "description": "The total number of contacts." + }, + "billable_count": { + "type": "integer", + "default": 0, + "description": "The count of contacts this month for billing purposes.", + "minimum": 0 + }, + "billable_breakdown": { + "type": "object", + "description": "`billable_breakdown` will only appear to the parent user in an account with subusers.", + "properties": { + "total": { + "type": "integer", + "description": "The sum of all the subuser's billable contacts" + }, + "breakdown": { + "type": "object", + "description": "A map of each subuser's billable contact usage. Each key is the subuser's ID and each value is the usage thus far this month.", + "minProperties": 0 + } + } + } + }, + "required": [ + "contact_count" + ] + } }, - { - "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" - ] + "401": { + "$ref": "#/responses/trait:globalErrors:401" }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" + "403": { + "$ref": "#/responses/trait:globalErrors:403" }, - { - "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" + "404": { + "$ref": "#/responses/trait:globalErrors:404" }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "Authorization": [] } + ] + } + }, + "/marketing/contacts/exports": { + "post": { + "operationId": "POST_mc-contacts-exports", + "summary": "Export Contacts", + "tags": [ + "Contacts" ], - "responses": { - "200": { - "description": "", + "description": "**Use this endpoint to export lists or segments of contacts**.\n\nIf you would just like to have a link to the exported list sent to your email set the `notifications.email` option to `true` in the `POST` payload.\n\nIf you would like to download the list, take the `id` that is returned and use the #endpoint:TrwE7WeCWP8hEbYis endpoint to get the `urls`. Once you have the list of URLs, make a `GET` request to each URL provided to download your CSV file(s).\n\nYou specify the segements and or/contact lists you wish to export by providing the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields in the request body.\n\nThe lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body `file_type` field to `json` or `csv`.\n\nYou can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files.", + "parameters": [ + { + "name": "body", + "in": "body", "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": { + "list_ids": { + "description": "IDs of the contact lists you want to export.", + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "segment_ids": { + "description": "IDs of the contact segments you want to export.", + "type": "array", + "items": { + "type": "string" + } + }, + "notifications": { + "type": "object", + "properties": { + "email": { + "type": "boolean" + } + } + }, + "file_type": { + "type": "string", + "enum": [ + "csv", + "json" + ], + "description": "File type for export file. Choose from `json` or `csv`.", + "default": "csv" + }, + "max_file_size": { + "description": "The maximum size of an export file in MB. Note that when this option is specified, multiple output files may be returned from the export.", + "default": 5000, + "type": "integer" + } + } + } + } + ], + "responses": { + "202": { + "description": "", + "schema": { + "type": "object", + "properties": { + "_metadata": { + "$ref": "#/definitions/metadata" + }, + "id": { + "type": "string", + "description": "The ID of the export job." + } + }, + "required": [ + "_metadata" + ] + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/definitions/error" + } + } + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_marketing-contacts-exports", + "summary": "Get All Existing Exports", + "tags": [ + "Contacts" + ], + "description": "**Use this endpoint to retrieve details of all current exported jobs**.\n\nIt will return an array of objects, each of which records an export job in flight or recently completed. \n\nEach object's `export_type` field will tell you which kind of export it is and its `status` field will indicate what stage of processing it has reached. Exports which are `ready` will be accompanied by a `urls` field which lists the URLs of the export's downloadable files — there will be more than one if you specified a maximum file size in your initial export request.\n\nUse this endpoint if you have exports in flight but do not know their IDs, which are required for #endpoint:TrwE7WeCWP8hEbYis.", + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Export jobs ID." + }, + "status": { + "type": "string", + "description": "Allowed values: `pending`, `ready`, or `failure`." + }, + "created_at": { + "type": "string", + "description": "This ISO8601 timestamp when the export was created." + }, + "completed_at": { + "type": "string", + "description": "This ISO8601 timestamp when the export was completed." + }, + "expires_at": { + "type": "string", + "description": "This ISO8601 timestamp when the export expires." + }, + "urls": { + "type": "array", + "description": "One or more download URLs for the contact file(s) if the status is `ready`.", + "items": { + "type": "string" + } + }, + "user_id": { + "type": "string", + "description": "User ID." + }, + "export_type": { + "type": "string", + "description": "Allowed types: `contacts_export`, `list_export`, or `segment_export`." + }, + "segments": { + "type": "array", + "items": { "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." + "ID": { + "type": "string" }, - "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." + "Name": { + "type": "string" + } + } + } + }, + "lists": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ID": { + "type": "string" }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." + "Name": { + "type": "string" } } } + }, + "_metadata": { + "type": "object", + "properties": { + "prev": { + "type": "string" + }, + "self": { + "type": "string" + }, + "next": { + "type": "string" + } + } } } } }, - "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 - } + "_metadata": { + "type": "object", + "properties": { + "prev": { + "type": "string" + }, + "self": { + "type": "string", + "description": "Link to this page." + }, + "next": { + "type": "string", + "description": "Link to next page." } - ] - }, - { - "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 + } + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "": { + "type": "string" + }, + "error_id": { + "type": "string" } - } - ] - }, - { - "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 - } - } - ] + }, + "required": [ + "message" + ] + } } - ] + } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -13217,1025 +12982,1051 @@ ] } }, - "/geo/stats": { + "/marketing/contacts/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_geo-stats", - "summary": "Retrieve email statistics by country and state/province.", + "operationId": "GET_mc-contacts-id", + "summary": "Get a Contact by ID", "tags": [ - "Stats" + "Contacts" ], - "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).", - "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" - ] + "description": "**This endpoint returns the full details and all fields for the specified contact**.", + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/contact-details3" + } }, - { - "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" + "401": { + "$ref": "#/responses/trait:globalErrors:401" }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. ", - "required": false, - "type": "string", - "default": "The date the request is made." + "403": { + "$ref": "#/responses/trait:globalErrors:403" }, - { - "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" - ] + "404": { + "description": "" }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" - }, + "Authorization": [] + } + ] + } + }, + "/marketing/contacts/search": { + "post": { + "operationId": "POST_mc-contacts-search", + "summary": "Search Contacts", + "tags": [ + "Contacts" + ], + "description": "**Use this endpoint to locate contacts**.\n\nThe request body's `query` field accepts valid [SGQL](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) for searching for a contact.\n\nOnly the first 50 contacts that meet the search criteria will be returned.\n\nIf the query takes longer than 20 seconds, a `408 Request Timeout` status will be returned.\n\nFormatting the `created_at` and `updated_at` values as Unix timestamps is deprecated. Instead they are returned as ISO format as string.", + "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "query": { + "type": "string", + "Description": "An SGQL search string or other pattern." + } + }, + "required": [ + "query" + ], + "example": { + "query": "email LIKE 'ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%' AND CONTAINS(list_ids, 'YOUR_LIST_IDs')" + } + } } ], "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 - } - } - ] + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/contact-details3" + } }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "_metadata": { + "$ref": "#/definitions/selfmetadata" }, - { - "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 + "contact_count": { + "type": "number", + "description": "The total number of contacts matched." + } + }, + "required": [ + "contact_count" + ] + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" } } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 + } + } + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "408": { + "description": "" + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" } } - ] + } + } + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/contacts/imports": { + "put": { + "operationId": "PUT_mc-contacts-imports", + "summary": "Import Contacts", + "tags": [ + "Contacts" + ], + "description": "**This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller.**\n\nImports take place asynchronously: the endpoint returns a URL (`upload_uri`) and HTTP headers (`upload_headers`) which can subsequently be used to `PUT` a file of contacts to be imported into our system.\n\nUploaded CSV files may also be [gzip-compressed](https://en.wikipedia.org/wiki/Gzip).\n\nIn either case, you must include the field `file_type` with the value `csv` in your request body.\n\nThe `field_mappings` paramter is a respective list of field definition IDs to map the uploaded CSV columns to. It allows you to use CSVs where one or more columns are skipped (`null`) or remapped to the contact field. \n\nFor example, if `field_mappings` is set to `[null, \"w1\", \"_rf1\"]`, this means skip column 0, map column 1 to the custom field with the ID `w1`, and map column 2 to the reserved field with the ID `_rf1`. See #endpoint:ShdXXCcwwTE39zYAT to fetch your custom and reserved field IDs to use with `field_mappings`.\n\nOnce you recieve the response body you can then initiate a **second** API call where you use the supplied URL and HTTP header to upload your file. For example:\n\n`curl --upload-file \"file/path.csv\" \"URL_GIVEN\" -H 'HEADER_GIVEN'`\n\nIf you'd like to monitor the status of your import job, use the `job_id` and the #endpoint:m5WnoiseMvTXuNwZt endpoint.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "list_ids": { + "type": "array", + "description": "All contacts will be added to each of the specified lists.", + "items": { + "type": "string" + } }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "file_type": { + "type": "string", + "enum": [ + "csv" + ], + "description": "Upload file type." }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 1, - "unique_clicks": 0, - "unique_opens": 1 + "field_mappings": { + "type": "array", + "description": "Import file header to reserved/custom field mapping.", + "uniqueItems": false, + "minItems": 1, + "items": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" } - } - ] + ] + } + } + }, + "required": [ + "file_type", + "field_mappings" + ] + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "job_id": { + "type": "string", + "description": "The ID of the import job." }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "upload_uri": { + "type": "string", + "description": "The URI to PUT the upload file to." }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 + "upload_headers": { + "type": "array", + "description": "A list of headers that must be included in PUT request.", + "items": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "value": { + "type": "string" } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 + }, + "required": [ + "header", + "value" + ] + } + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "uniqueItems": true, + "properties": { + "errors": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/error" + } + } + }, + "required": [ + "errors" + ] + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "type": "object", + "description": "If any of the specified lists do not exist.", + "uniqueItems": true, + "properties": { + "errors": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/error" + } + } + }, + "required": [ + "errors" + ] + } + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/contacts/imports/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_marketing-contacts-imports-id", + "summary": "Import Contacts Status", + "tags": [ + "Contacts" + ], + "description": "**This endpoint can be used to check the status of a contact import job**. \n\nUse the `job_id` from the #endpoint:LPe3yJSpmGyv39oTa, #endpoint:rAGcTKvL5Q3XQd8Xp, or #endpoint:oazoY5DJsLqGMPfNY as the `id` in the path parameter.\n\nIf there is an error with your `PUT` request, download the `errors_url` file and open it to view more details.\n\nThe job `status` field indicates whether the job is `pending`, `completed`, `errored`, or `failed`. \n\nPending means not started. Completed means finished without any errors. Errored means finished with some errors. Failed means finshed with all errors, or the job was entirely unprocessable: for example, if you attempt to import file format we do not support.\n\nThe `results` object will have fields depending on the job type.", + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/contact-import" + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "$ref": "#/definitions/error" + } + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/contacts/exports/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_mc-contacts-exports-id", + "summary": "Export Contacts Status", + "tags": [ + "Contacts" + ], + "description": "**This endpoint can be used to check the status of a contact export job**. \n\nTo use this call, you will need the `id` from the #endpoint:aQ42cqyfw3XHCMdfY call.\n\nIf you would like to download a list, take the `id` that is returned from #endpoint:aQ42cqyfw3XHCMdfY and make an API request here to get the `urls`. Once you have the list of URLs, make a `GET` request on each URL to download your CSV file(s).", + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/contact-export" + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/definitions/error" + } + } + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/contacts/batch": { + "post": { + "operationId": "POST_marketing-contacts-batch", + "summary": "Get Batched Contacts by IDs", + "tags": [ + "Contacts" + ], + "description": "**This endpoint is used to retrieve a set of contacts identified by their IDs.**\n\nThis can be more efficient endpoint to get contacts than making a series of individual `GET` requests to #endpoint:f8xTRGmJGQ5bsgGaR.\n\nYou can supply up to 100 IDs. Pass them into the `ids` field in your request body as an array or one or more strings.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "description": "Array of IDs", + "properties": { + "ids": { + "maxLength": 100, + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "ids" + ] + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/contact-details3" + } + } + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "type": "object" + } + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + } + } + }, + "/marketing/contacts/search/emails": { + "post": { + "operationId": "POST_marketing-contacts-search-emails", + "summary": "Get Contacts by Emails", + "tags": [ + "Contacts" + ], + "description": "**This endpoint allows you to retrieve up to 100 contacts matching the searched `email` address(es), including any `alternate_emails`.** \n\nEmail addresses are unique to a contact, meaning this endpoint can treat an email address as a primary key to search by. The contact object associated with the address, whether it is their `email` or one of their `alternate_emails` will be returned if matched.\n\nEmail addresses are not case sensitive, and returned email addresses will be all lower case. Empty strings are excluded from the search and will not be returned.\n\nThis endpoint should be used in place of the #endpoint:5oj27hT9p3TLXNBJP endpoint when you can provide exact email addresses and do not need to include other [Segmentation Query Language (SGQL)](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) filters when searching.\n\nIf you need to access a large percentage of your contacts, we recommend exporting your contacts with the #endpoint:aQ42cqyfw3XHCMdfY endpoint and filtering the results client side.\n\nThis endpoint returns a `200` status code when any contacts match the address(es) you supplied. When searching multiple addresses in a single request, it is possible that some addresses will match a contact while others will not. When a partially successful search like this is made, the matching contacts are returned in an object and an error message is returned for the email address(es) that are not found. \n\nThis endpoint returns a `404` status code when no contacts are found for the provided email address(es).\n\nA `400` status code is returned if any searched addresses are invalid.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "description": "", + "properties": { + "emails": { + "type": "array", + "description": "One or more primary emails and/or alternate emails to search through your contacts for.", + "items": { + "type": "string", + "maxLength": 100 + } + } + }, + "required": [ + "emails" + ], + "example": { + "emails": [ + "jane_doe@example.com", + "john_doe@example.com", + "joann_doe@example.com" + ] + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^[A-Za-z0-9\\._%\\+-]+@[A-Za-z0-9\\.-]+\\.[A-Za-z]{2,6}$": { + "type": "object", + "description": "This will be one of the specified email adresses.", + "properties": { + "contact": { + "$ref": "#/definitions/contact-details3" + }, + "error": { + "type": "string" + } } } - ] - }, - { - "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 + } + } + } + }, + "examples": { + "application/json": { + "result": { + "jane_doe@example.com": { + "contact": { + "address_line_1": "", + "address_line_2": "", + "alternate_emails": [ + "janedoe@example1.com" + ], + "city": "", + "country": "", + "email": "jane_doe@example.com", + "first_name": "Jane", + "id": "asdf-Jkl-zxCvBNm", + "last_name": "Doe", + "list_ids": [], + "segment_ids": [], + "postal_code": "", + "state_province_region": "", + "phone_number": "", + "whatsapp": "", + "line": "", + "facebook": "", + "unique_name": "", + "custom_fields": {}, + "created_at": "2021-03-02T15:25:47Z", + "updated_at": "2021-03-30T15:26:16Z", + "_metadata": { + "self": "" } } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 + }, + "john_doe@example.com": { + "contact": { + "address_line_1": "", + "address_line_2": "", + "alternate_emails": [], + "city": "", + "country": "", + "email": "john_doe@example.com", + "first_name": "Jane", + "id": "asdf-Jkl-qWeRTy", + "last_name": "Doe", + "list_ids": [], + "segment_ids": [], + "postal_code": "", + "state_province_region": "", + "phone_number": "", + "whatsapp": "", + "line": "", + "facebook": "", + "unique_name": "", + "custom_fields": {}, + "created_at": "2020-01-02T15:25:47Z", + "updated_at": "2020-12-20T15:26:16Z", + "_metadata": { + "self": "" } } - ] - }, - { - "date": "2015-10-28", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 + }, + "joann_doe@example.com": { + "error": "contact not found" + } + } + } + } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" } } - ] + } + } + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/senders": { + "post": { + "operationId": "POST_marketing-senders", + "summary": "Create a Sender Identity", + "tags": [ + "Senders" + ], + "description": "**This endpoint allows you to create a new sender identity.**\n\n*You may create up to 100 unique sender identities.*\n\nSender identities are required to be verified before use. If your domain has been authenticated, a new sender identity will auto verify on creation. Otherwise an email will be sent to the `from.email`.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "nickname": { + "type": "string", + "description": "A nickname for the sender identity. Not used for sending." }, - { - "date": "2015-10-29", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } + "from": { + "type": "object", + "required": [ + "email", + "name" + ], + "properties": { + "email": { + "type": "string", + "description": "This is where the email will appear to originate from for your recipient" + }, + "name": { + "type": "string", + "description": "This is the name appended to the from email field. IE - Your name or company name." } - ] + } }, - { - "date": "2015-10-30", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } + "reply_to": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is the email that your recipient will reply to." + }, + "name": { + "type": "string", + "description": "This is the name appended to the reply to email field. IE - Your name or company name." } + }, + "required": [ + "email" ] }, - { - "date": "2015-10-31", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "address": { + "type": "string", + "description": "The physical address of the sender identity." }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "address_2": { + "type": "string", + "description": "Additional sender identity address information." }, - { - "date": "2015-11-02", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "city": { + "type": "string", + "description": "The city of the sender identity." }, - { - "date": "2015-11-03", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "state": { + "type": "string", + "description": "The state of the sender identity." }, - { - "date": "2015-11-04", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "zip": { + "type": "string", + "description": "The zipcode of the sender identity." }, - { - "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 - } - } - ] + "country": { + "type": "string", + "description": "The country of the sender identity." + } + }, + "required": [ + "nickname", + "from", + "address", + "city", + "country" + ], + "example": { + "nickname": "Example Orders", + "from": { + "email": "orders@example.com", + "name": "Example Orders" }, - { - "date": "2015-11-09", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] + "reply_to": { + "email": "support@example.com", + "name": "Example Support" }, - { - "date": "2015-11-10", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - } - ] + "address": "1234 Fake St.", + "address_2": "", + "city": "San Francisco", + "state": "CA", + "zip": "94105", + "country": "United States" + } } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } - } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/senderID" + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] } }, - "/devices/stats": { - "get": { - "operationId": "GET_devices-stats", - "summary": "Retrieve email statistics by device type.", + "/marketing/lists": { + "post": { + "operationId": "POST_mc-lists", + "summary": "Create List", "tags": [ - "Stats" - ], - "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).", - "produces": [ - "application/json" + "Lists" ], + "description": "**This endpoint creates a new contacts list.**\n\nOnce you create a list, you can use the UI to [trigger an automation](https://sendgrid.com/docs/ui/sending-email/getting-started-with-automation/#create-an-automation) every time you add a new contact to the list.\n\nA link to the newly created object is in `_metadata`.", "parameters": [ { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today.", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Your name for your list", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "name" + ], + "example": { + "name": "list-name" + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/list" + }, + "examples": { + "application/json": { + "id": "ca7a3796-e8a8-4029-9ccb-df8937940562", + "name": "list-name", + "contact_count": 0, + "_metadata": { + "self": "https://api.sendgrid.com/v3/marketing/lists/ca7a3796-e8a8-4029-9ccb-df8937940562" + } + } + } }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/definitions/error" + } + } + } + } + } + }, + "security": [ { - "name": "limit", - "in": "query", - "description": "How many results to include on each page.", - "required": false, - "type": "integer" - }, + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_mc-lists", + "summary": "Get All Lists", + "tags": [ + "Lists" + ], + "description": "**This endpoint returns an array of all of your contact lists.**", + "parameters": [ { - "name": "offset", + "name": "page_size", "in": "query", - "description": "How many results to exclude.", + "description": "Maximum number of elements to return. Defaults to 100, returns 1000 max", "required": false, - "type": "integer" + "type": "number", + "default": 100, + "minimum": 1, + "maximum": 1000 }, { - "name": "aggregated_by", + "name": "page_token", "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" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/list" + } + }, + "_metadata": { + "$ref": "#/definitions/metadata" + } } }, "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 - } + "application/json": { + "result": [ + { + "id": "abc12312-x3y4-1234-abcd-123qwe456rty", + "name": "list-name", + "contact_count": 0, + "_metadata": { + "self": "https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty" } - ] - }, - { - "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 - } - } - ] + } + ], + "_metadata": { + "self": "https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token=" + } + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/lists/{id}/contacts/count": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_mc-lists-id-contacts-count", + "summary": "Get List Contact Count", + "tags": [ + "Lists" + ], + "description": "**This endpoint returns the number of contacts on a specific list.**", + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "contact_count": { + "type": "integer" }, + "billable_count": { + "type": "integer" + } + } + }, + "examples": { + "application/json": { + "contact_count": 0, + "billable_count:": 0 + } + } + }, + "404": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/lists/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_mc-lists-id", + "summary": "Get a List by ID", + "tags": [ + "Lists" + ], + "description": "**This endpoint returns data about a specific list.**\n\nSetting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to fifty of the most recent contacts uploaded or attached to a list will be returned, sorted alphabetically, by email address.\n\nThe full contact count is also returned.", + "parameters": [ + { + "name": "contact_sample", + "in": "query", + "description": "Setting this parameter to the true will cause the contact_sample to be returned", + "type": "boolean", + "default": false + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "allOf": [ { - "date": "2015-10-24", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] + "$ref": "#/definitions/list" }, { - "date": "2015-10-25", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } + "type": "object", + "properties": { + "contact_sample": { + "$ref": "#/definitions/contact-details2" } - ] + } + } + ] + }, + "examples": { + "application/json": { + "contact_count": 2, + "contact_sample": { + "id": "c3445f88-5c69-4237-86e6-9ec9de958050", + "list_ids": [ + "199abb98-0af3-4a8d-b371-6811ff85d062" + ], + "created_at": "2620-06-16T17:03:54.867Z", + "updated_at": "4780-12-06T06:51:30.024Z" }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 2, - "unique_opens": 2 - } - } - ] + "_metadata": { + "self": "https://api.sendgrid.com/v3/marketing/lists/199abb98-0af3-4a8d-b371-6811ff85d062" }, - { - "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 - } - } - ] - } - ] + "id": "199abb98-0af3-4a8d-b371-6811ff85d062", + "name": "list-name" + } + } + }, + "404": { + "description": "", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/error" + } } } }, @@ -14244,87 +14035,133 @@ "Authorization": [] } ] - } - }, - "/clients/stats": { - "get": { - "operationId": "GET_clients-stats", - "summary": "Retrieve email statistics by client type.", + }, + "patch": { + "operationId": "PATCH_mc-lists-id", + "summary": "Update List", "tags": [ - "Stats" - ], - "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).", - "produces": [ - "application/json" + "Lists" ], + "description": "**This endpoint updates the name of a list.**", "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" - ] - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Your name for your list." + } + }, + "example": { + "name": "updated-list-name" + } + } } ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" + "$ref": "#/definitions/list" + }, + "examples": { + "application/json": { + "id": "abc12312-x3y4-1234-abcd-123qwe456rty", + "name": "updated-list-name", + "contact_count": 0, + "_metadata": { + "self": "https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty" + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/definitions/error" + } + } + } + } + }, + "404": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_lists-id", + "summary": "Delete a list", + "tags": [ + "Lists" + ], + "description": "**This endpoint allows you to deletes a specific list.**\n\nOptionally, you can also delete contacts associated to the list. The query parameter, `delete_contacts=true`, will delete the list and start an asynchronous job to delete associated contacts.", + "parameters": [ + { + "name": "delete_contacts", + "in": "query", + "description": "Flag indicates that all contacts on the list are also to be deleted.", + "required": false, + "type": "boolean", + "default": false + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "description": "The delete has been accepted and is processing.", + "properties": { + "job_id": { + "type": "string", + "description": "job_id of the async job" + } } }, "examples": { - "application/json": [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] + "application/json": { + "job_id": "abc12312-x3y4-1234-abcd-123qwe456rty" + } + } + }, + "204": { + "description": "", + "schema": { + "type": "string", + "description": "The delete has been processed. " + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object" + } } + }, + "required": [ + "errors" ] } } @@ -14336,101 +14173,152 @@ ] } }, - "/clients/{client_type}/stats": { + "/marketing/lists/{id}/contacts": { "parameters": [ { - "name": "client_type", + "name": "id", "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" - ] + "type": "string" } ], - "get": { - "operationId": "GET_clients-client_type-stats", - "summary": "Retrieve stats by a specific client type.", + "delete": { + "operationId": "DELETE_mc-lists-id-contacts", + "summary": "Remove Contacts from a List", "tags": [ - "Stats" - ], - "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).", - "produces": [ - "application/json" + "Lists" ], + "description": "**This endpoint allows you to remove contacts from a given list.**\n\nThe contacts will not be deleted. Only their list membership will be changed.", "parameters": [ { - "name": "start_date", + "name": "contact_ids", "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "description": "comma separated list of contact ids", "required": true, - "type": "string" + "type": "string", + "minLength": 1 + } + ], + "responses": { + "202": { + "description": "", + "schema": { + "type": "object", + "description": "The removal is accepted and processing.", + "properties": { + "job_id": { + "type": "string", + "description": "job_id of the async job" + } + } + } }, - { - "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" + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/error" + } }, + "404": { + "description": "", + "schema": { + "description": "If the specified list id does not exist. If the specified contact does not exist." + } + } + }, + "security": [ { - "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" - ] - }, + "Authorization": [] + } + ] + } + }, + "/marketing/field_definitions": { + "post": { + "operationId": "POST_mc-field_definitions", + "summary": "Create Custom Field Definition", + "tags": [ + "Custom Fields" + ], + "description": "**This endpoint creates a new custom field definition.**\n\nCustom field definitions are created with the given `name` and `field_type`. Although field names are stored in a case-sensitive manner, all field names must be case-insensitively unique. This means you may create a field named `CamelCase` or `camelcase`, but not both. Additionally, a Custom Field name cannot collide with any Reserved Field names. You should save the returned `id` value in order to update or delete the field at a later date. You can have up to 120 custom fields.\n\nThe custom field name should be created using only alphanumeric characters (A-Z and 0-9) and underscores (\\_). Custom fields can only begin with letters A-Z or underscores (_). The field type can be date, text, or number fields. The field type is important for creating segments from your contact database.\n\n**Note: Creating a custom field that begins with a number will cause issues with sending in Marketing Campaigns.**", + "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "field_type": { + "type": "string", + "enum": [ + "Text", + "Number", + "Date" + ] + } + }, + "required": [ + "name", + "field_type" + ], + "example": { + "name": "custom_field_name", + "field_type": "Text" + } + } } ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - }, - "examples": { - "application/json": [ + "allOf": [ { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] + "$ref": "#/definitions/custom_field_definitions_response" }, { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" + "type": "object", + "properties": { + "_metadata": { + "$ref": "#/definitions/_metadata" } - ] + } } ] + }, + "examples": { + "application/json": { + "id": "a1_T", + "name": "custom_field_name", + "field_type": "Text", + "_metadata": { + "self": "https://api.sendgrid.com/v3/marketing/field_definitions/a1_B" + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "uniqueItems": true, + "properties": { + "errors": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/error" + } + } + }, + "required": [ + "errors" + ] } } }, @@ -14439,734 +14327,1269 @@ "Authorization": [] } ] - } - }, - "/mailbox_providers/stats": { + }, "get": { - "operationId": "GET_mailbox_providers-stats", - "summary": "Retrieve email statistics by mailbox provider.", + "operationId": "GET_mc-field_definitions", + "summary": "Get All Field Definitions", "tags": [ - "Stats" - ], - "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).", - "produces": [ - "application/json" + "Custom Fields" ], - "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" - }, + "description": "**This endpoint retrieves all defined Custom Fields and Reserved Fields.**", + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "uniqueItems": true, + "properties": { + "custom_fields": { + "type": "array", + "minitems": 0, + "manitems": 120, + "items": { + "$ref": "#/definitions/custom_field_definitions_response" + } + }, + "reserved_fields": { + "$ref": "#/definitions/reserved_field_definitions_response" + }, + "_metadata": { + "$ref": "#/definitions/_metadata" + } + }, + "required": [ + "custom_fields", + "reserved_fields" + ] + }, + "examples": { + "application/json": { + "custom_fields": [ + { + "id": "w1", + "name": "num_orders", + "field_type": "Number" + }, + { + "id": "w2", + "name": "dob", + "field_type": "Date" + } + ], + "reserved_fields": [ + { + "id": "_rf0_T", + "name": "first_name", + "field_type": "Text" + }, + { + "id": "_rf1_T", + "name": "last_name", + "field_type": "Text" + }, + { + "id": "_rf2_T", + "name": "email", + "field_type": "Text" + }, + { + "id": "_rf3_T", + "name": "alternate_emails", + "field_type": "Text" + }, + { + "id": "_rf4_T", + "name": "address_line_1", + "field_type": "Text" + }, + { + "id": "_rf5_T", + "name": "address_line_2", + "field_type": "Text" + }, + { + "id": "_rf6_T", + "name": "city", + "field_type": "Text" + }, + { + "id": "_rf7_T", + "name": "state_province_region", + "field_type": "Text" + }, + { + "id": "_rf8_T", + "name": "postal_code", + "field_type": "Text" + }, + { + "id": "_rf9_T", + "name": "country", + "field_type": "Text" + }, + { + "id": "_rf10_T", + "name": "phone_number", + "field_type": "Text" + }, + { + "id": "_rf11_T", + "name": "whatsapp", + "field_type": "Text" + }, + { + "id": "_rf12_T", + "name": "line", + "field_type": "Text" + }, + { + "id": "_rf13_T", + "name": "facebook", + "field_type": "Text" + }, + { + "id": "_rf14_T", + "name": "unique_name", + "field_type": "Text" + }, + { + "id": "_rf15_T", + "name": "email_domains", + "field_type": "Text", + "read_only": true + }, + { + "id": "_rf16_D", + "name": "last_clicked", + "field_type": "Date", + "read_only": true + }, + { + "id": "_rf17_D", + "name": "last_opened", + "field_type": "Date", + "read_only": true + }, + { + "id": "_rf18_D", + "name": "last_emailed", + "field_type": "Date", + "read_only": true + }, + { + "id": "_rf19_T", + "name": "singlesend_id", + "field_type": "Text", + "read_only": true + }, + { + "id": "_rf20_T", + "name": "automation_id", + "field_type": "Text", + "read_only": true + }, + { + "id": "_rf21_D", + "name": "created_at", + "field_type": "Date", + "read_only": true + }, + { + "id": "_rf22_D", + "name": "updated_at", + "field_type": "Date", + "read_only": true + }, + { + "id": "_rf23_T", + "name": "contact_id", + "field_type": "Text", + "read_only": true + } + ], + "_metadata": { + "self": "https://example.com/marketing/field_definitions" + } + } + } + } + }, + "security": [ { - "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" - }, + "Authorization": [] + } + ] + } + }, + "/marketing/field_definitions/{custom_field_id}": { + "parameters": [ + { + "name": "custom_field_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "patch": { + "operationId": "PATCH_mc-field_definitions-custom_field_id", + "summary": "Update Custom Field Definition", + "tags": [ + "Custom Fields" + ], + "description": "**This endopoint allows you to update a defined Custom Field.**\n\nOnly your Custom fields can be modified; Reserved Fields cannot be updated.", + "parameters": [ { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "name" + ], + "example": { + "name": "new_custom_field_name" + } + } } ], "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 - } - } - ] - }, + "allOf": [ { - "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/custom_field_definitions_response" }, { - "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 - } + "type": "object", + "properties": { + "_metadata": { + "$ref": "#/definitions/_metadata" } - ] - }, - { - "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 - } - } - ] - }, + } + } + ] + }, + "examples": { + "application/json": { + "id": "a1_T", + "name": "custom_field_name", + "field_type": "Text", + "_metadata": { + "self": "https://api.sendgrid.com/v3/marketing/field_definitions/a1_B" + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "uniqueItems": true, + "properties": { + "errors": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/error" + } + } + }, + "required": [ + "errors" + ] + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "uniqueItems": true, + "properties": { + "errors": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/error" + } + } + }, + "required": [ + "errors" + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_mc-field_definitions-custom_field_id", + "summary": "Delete Custom Field Definition", + "tags": [ + "Custom Fields" + ], + "description": "**This endpoint deletes a defined Custom Field.**\n\nYou cand delete only Custom Fields; Reserved Fields cannot be deleted.", + "responses": { + "204": { + "description": "" + }, + "404": { + "description": "", + "schema": { + "type": "object", + "required": [ + "errors" + ], + "properties": { + "errors": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/definitions/error" + } + } + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/segments": { + "post": { + "operationId": "POST_marketing-segments", + "summary": "Create Segment", + "tags": [ + "segmenting contacts", + "Segmenting Contacts" + ], + "description": "**This endpoint allows you to create a segment.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "allOf": [ { - "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 - } - } - ] + "$ref": "#/definitions/segment_write" }, { - "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 - } + "type": "object", + "properties": { + "parent_list_id": { + "type": "string", + "minLength": 36, + "maxLength": 36, + "format": "uuid", + "description": "The id of the list if this segment is a child of a list. This implies the query is rewritten as `(${query_dsl}) AND CONTAINS(list_ids, ${parent_list_id})`" } + } + } + ] + } + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/full-segment" + }, + "examples": { + "application/json": { + "id": "864feb2e-5e93-47bf-b63e-21746c988105", + "contacts_count": 0, + "created_at": "mollit labore aute deserunt ad", + "sample_updated_at": "enim culpa in", + "updated_at": "minim", + "contact_summary": { + "contact_id": "1a541ca7-9fef-42c8-8947-f3f8a3b33ffe", + "primary_email": "D8OsYF5ok@YtX.kcg", + "first_name": "exercitation Duis nisi", + "last_name": "aut", + "address_line_1": "ut sunt Duis eu", + "address_line_2": "in culpa esse non", + "city": "ÔXƫɋƄř", + "state_province_region": "consequat culpa in", + "postal_code": -88086402, + "country": "eiusmod", + "custom_fields": { + "custom_field_name2": "dolore cillum", + "custom_field_name1": "est mollit officia adipisicing dolo" + }, + "list_ids": [ + "c856a255-12f1-4b55-8564-218fd7eb34a7", + "130c8813-0d6f-4b9e-b154-736bb9db2ff8", + "c245021d-4444-4086-a498-3ffee7fa8cdf" ] }, - { - "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 + "name": "aute amet deserunt adipisicing", + "query_dsl": "email LIKE %twilio.com", + "next_sample_update": "culpa sit occaecat fugiat quis" + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" } - } - ] - }, - { - "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 + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_marketing-segments", + "summary": "Get List of Segments", + "tags": [ + "segmenting contacts", + "Segmenting Contacts" + ], + "description": "**This endpoint allows you to retrieve a list of segments.**\n\nThe query param `parent_list_ids` is treated as a filter. Any match will be returned. 0 matches will return a response code of 200 with an empty `results` array.\n\n`parent_list_ids` | `no_parent_list_id` | `result`\n-----------------:|:--------------------:|:-------------\nempty | false | all segments\nvalues | false | segments filtered by list_ids\nvalues | true | segments filtered by list_ids and segments with no parent list_ids\nempty | true | segments with no parent list_ids", + "parameters": [ + { + "name": "parent_list_ids", + "in": "query", + "description": "A comma separated list of list ids to be used when searching for segments with the specified parent_list_id, no more than 50 is allowed", + "type": "string" + }, + { + "name": "no_parent_list_id", + "in": "query", + "description": "If set to `true` segments with an empty value of `parent_list_id` will be returned in the filter. If the value is not present it defaults to 'false'.", + "type": "boolean", + "default": false + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "results": { + "type": "array", + "uniqueItems": true, + "minItems": 0, + "items": { + "$ref": "#/definitions/segment_summary" + } + } + }, + "required": [ + "results" + ] + }, + "examples": { + "application/json": { + "results": [ + { + "id": "12099613-91e5-4d09-a900-df7626325288", + "contacts_count": 78434802, + "created_at": "2921-01-27T19:33:36.479Z", + "sample_updated_at": "4685-11-26T07:05:04.660Z", + "updated_at": "2883-07-10T13:13:37.697Z" + }, + { + "id": "60c37015-3734-4c8e-b293-68cfa2ae4fa5", + "contacts_count": 34177253, + "created_at": "2575-07-26T23:17:20.984Z", + "sample_updated_at": "3074-09-04T09:49:58.127Z", + "updated_at": "5116-10-15T07:37:40.838Z", + "parent_list_id": "fd38af3d-3f69-4947-8dca-5fa967e7be82", + "name": "amet" + } + ] + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" } + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/segments/{segment_id}": { + "parameters": [ + { + "name": "segment_id", + "in": "path", + "required": true, + "type": "string", + "minLength": 36, + "maxLength": 36, + "format": "uuid" + } + ], + "get": { + "operationId": "GET_marketing-segments-segment_id", + "summary": "Get Segment by ID", + "tags": [ + "segmenting contacts", + "Segmenting Contacts" + ], + "description": "**This endpoint allows you to retrieve a single segment by ID.**", + "parameters": [ + { + "name": "query_json", + "in": "query", + "description": "Defaults to `false`. Set to `true` to return the parsed SQL AST as a JSON object in the field `query_json`", + "type": "boolean" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/full-segment" + }, + "examples": { + "application/json": { + "id": "3b049926-0a54-4a91-83f0-086ace63c530", + "contacts_count": -83213117, + "created_at": "voluptate sunt non fugiat", + "sample_updated_at": "labore occaecat sunt enim", + "updated_at": "sunt aliqui", + "contacts_sample": [ + { + "contact_id": "e70eac25-1431-4231-bccd-1cfab432301e", + "primary_email": "KLTF@SurgGzlAxCPOqhOUHYNBLsfpfE.trh", + "alternate_emails": [ + "dTeJZgU5uN9UYSo@nfIB.ijxg" + ], + "first_name": "ullamco esse culpa do", + "last_name": "officia laboris veniam consequat", + "address_line_1": "in occaecat labore est tempor", + "address_line_2": "magna adipisicing", + "city": "ƞó", + "state_province_region": "culpa ut", + "postal_code": -75218567, + "country": "voluptate in in reprehenderit aliquip", + "custom_fields": { + "custom_field_name1": "amet deserunt mollit", + "custom_field_name2": "minim consequat id" } - ] - }, - { - "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 + }, + { + "contact_id": "db637d33-bce1-462c-ae9c-91ec4f761de6", + "primary_email": "t7N5TjDmKhC0@gfdifW.ua", + "alternate_emails": [ + "gQol@Xcfilli.hc", + "n4K7OdaVQh@YfsnF.ie", + "TdnvS3nMStREn@miFjGzNDCPZWhiswJNxrFnOYdUAZEpesQ.yxpu", + "xRzGDTTzzbYK@eJ.wpgb", + "iI1rOpx2ct@aZhuYGZBxJLZ.phr" + ], + "first_name": "ea et eu", + "last_name": "velit Ut laborum ipsu", + "address_line_1": "labore", + "address_line_2": "non", + "city": "ĔȸąŸÂ¸ȠɏbɄ", + "state_province_region": "deserunt dolore", + "postal_code": -95171713, + "country": "do", + "list_ids": [ + "c712288b-2300-4069-bef4-2e05b5948ec3", + "9003ef29-5eb7-4951-898b-1b102e490d6e" + ] + } + ], + "name": "enim et anim", + "query_dsl": "nostrud" + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" } - } - ] - }, - { - "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 + }, + "required": [ + "message", + "field" + ] + } + } + }, + "required": [ + "errors" + ] + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" } + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_marketing-segments-segment_id", + "summary": "Update Segment", + "tags": [ + "segmenting contacts", + "Segmenting Contacts" + ], + "description": "**This endpoint allows you to update a segment.**\n\nSegment `name` needs to be unique. A user can not update a segment name to an existing one.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/segment_write" + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/full-segment" + }, + "examples": { + "application/json": { + "id": "5fff6250-b766-4959-a183-2e1fa565c4ce", + "contacts_count": -35493018, + "created_at": "2014-12-23T17:18:52.907Z", + "sample_updated_at": "2146-04-13T16:46:32.328Z", + "updated_at": "4389-06-21T16:59:51.403Z", + "contacts_sample": [ + { + "contact_id": "4cff9fdf-1bee-44f7-95dc-a101f9ed3cfe", + "primary_email": "exmS@KIzibBSmaUUHQa.uvv", + "alternate_emails": [ + "qXP-RD97fLl@oEDaUynqnNRHJHdoJAWVGXwvI.qlv", + "W0ngFWmR@WcQuSbPFVPZvLrjCFadfimFi.eqf", + "mYBC0ea5UxFI@qwO.jh", + "Nhf1OmY@KCSjTQsXYpbKrBUsQFHrnLuY.oef" + ], + "first_name": "consequat nulla in", + "last_name": "irure nostrud elit eu", + "address_line_1": "deserunt cillum aliqua nostrud ullamco", + "address_line_2": "sint", + "city": "ŷ(ç", + "state_province_region": "minim", + "postal_code": 62721676, + "country": "consectetur quis voluptate", + "list_ids": [ + "f9d5987d-7a01-4a66-b77e-1f08a392304b", + "b4e3b028-01d4-428b-9ef5-24bcd90fa02c", + "fedab84f-9aa5-449d-99e2-7b1361f8ee61" + ] + }, + { + "contact_id": "093a66b8-bca8-4d8a-b32a-091d939c1928", + "primary_email": "atNeYGC4nbF42@VOCUWuGaYr.ystm", + "alternate_emails": [ + "Zs6vnQbMU@XTamDsXEGJWBMMEacOc.hitv", + "Epl@ySBrQCFJZnjggkAYLu.ppta" + ], + "first_name": "est", + "last_name": "in", + "address_line_1": "culpa eu eiusmod sint", + "address_line_2": "sed velit sint", + "city": "BĊJ", + "state_province_region": "Lorem Ut aliqua elit", + "postal_code": 33736880, + "country": "in laboris Excepteur consequat", + "custom_fields": { + "custom_field_name2": "culpa Excepteur", + "custom_field_name1": "esse magna Ut" } - ] - }, - { - "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 + }, + { + "contact_id": "08939f9c-2c87-4639-bd07-16d41f90a5eb", + "primary_email": "Jx660QHClqRrC@SavQvcdRpJlLqepwoEUCm.ar", + "alternate_emails": [ + "S8u@ZVGjHsXdSWtlhhad.ximc", + "GA1MN72v3uA@MPDvMUmTYjwFCsEaGnFnvVzJVqUTl.ehws" + ], + "first_name": "sed eu veli", + "last_name": "aliqua sit culpa", + "address_line_1": "occaecat aute enim", + "address_line_2": "ipsum quis in", + "city": "ɌſĕĝȤ¶Ǖ", + "state_province_region": "ut nisi sed esse", + "postal_code": -66445052, + "country": "occaecat veniam" + }, + { + "contact_id": "0667ed97-7b7b-44aa-a115-0301067660d7", + "primary_email": "AnoFtJq@IolRDmfj.njt", + "alternate_emails": [ + "F5WhHCA3oL6Ix@wOKzwIsvHbFi.mrlc" + ], + "first_name": "do mollit velit", + "last_name": "voluptate dolor", + "address_line_1": "et incididunt", + "address_line_2": "veniam quis non exercitation Duis", + "city": "DzƐȹŲdž", + "state_province_region": "occaecat", + "postal_code": -19694583, + "country": "reprehenderit", + "custom_fields": { + "custom_field_name1": "dolor aute irure Excepteur" + }, + "list_ids": [ + "ffd225a8-2008-4457-87af-1cffff5b1ccb" + ] + }, + { + "contact_id": "449767ca-d446-45f1-aa9b-432f441b5ca1", + "primary_email": "kF4@gYYdAxzetJrWszLAHuBUTu.rzq", + "alternate_emails": [ + "ksqbx6BInlB@ouWBjjxwFBwVQjdnEKXy.xi", + "TAe7F2m8dFlF@SirYykzbe.aj", + "T9c2Y@HjVQY.zz", + "p7ShfET@vMMnTUqoqngPSEqbpyoeWN.jlqn", + "0VJSIhIUT2k@mJXVtdZVKKswW.xoca" + ], + "first_name": "irure laboris minim", + "last_name": "id nostrud aliqua sit", + "address_line_1": "dolor", + "address_line_2": "elit ex labore sunt aliquip", + "city": "ÝǘźƝǝƉ‘Ɲ", + "state_province_region": "nostrud Duis non nulla laborum", + "postal_code": 60466925, + "country": "id sunt nisi", + "custom_fields": { + "custom_field_name2": "enim quis", + "custom_field_name1": "amet" + }, + "list_ids": [ + "2870627c-b9ea-4dcf-bde0-36c3e0e3eca9", + "575d86aa-4dcc-4b7d-b7de-ded856913198", + "fb82a17f-5777-439d-9b8c-2c565c8ddf20" + ] + } + ], + "name": "List Name", + "query_dsl": "Email LIKE %twilio.com" + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" } - } - ] - }, - { - "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 + }, + "required": [ + "message", + "field" + ] + } + } + }, + "required": [ + "errors" + ] + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" } - } - ] - }, - { - "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 + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_marketing-segments-segment_id", + "summary": "Delete Segment", + "tags": [ + "segmenting contacts", + "Segmenting Contacts" + ], + "description": "**This endpoint allows you to delete a segment by `segment_id`.**\n\nNote that deleting a segment does not delete the contacts associated with the segment by default. Contacts associated with a deleted segment will remain in your list of all contacts and any other segments they belong to.", + "responses": { + "202": { + "description": "", + "schema": { + "type": "object" + } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/error_schema" + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" } - } - ] - }, - { - "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 + }, + "required": [ + "message", + "field" + ] + } + } + }, + "required": [ + "errors" + ] + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" } - } - ] - }, - { - "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 + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/segments/delete": { + "post": { + "operationId": "POST_marketing-segments-delete", + "summary": "Bulk Delete Segments", + "tags": [ + "Segmenting Contacts" + ], + "description": "This endpoint allows you to delete segments in bulk.\n\nIf the segments are used by automations or the segments do not exist in the database, the segment IDs that could not be deleted along with automation IDs that are associated to those segments will be returned.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + } + }, + "example": { + "ids": [ + "a14dcc63-d651-4c57-9826-4a3705f5c78d", + "f3de551e-dc5c-4d42-bd08-c7f87f87f0e8", + "1b8107b5-adf4-401c-8865-fa84ba178fb9", + "d7900715-c904-4728-acff-9ab79627579e", + "16641f5b-cfa3-41b9-9626-244488ee85b1" + ] + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Segment ID" + }, + "error": { + "type": "string", + "description": "error message that indicates why segment cannot be deleted (\"in-use\", \"segment not found\", \"invalid uuid\")" + }, + "resources": { + "type": "object", + "description": "resources in which segment is being used", + "properties": { + "type": { + "type": "string", + "description": "the type of resource in use (e.g., \"automation\")" + }, + "ids": { + "type": "array", + "description": "the resource ids", + "items": { + "type": "string" + } + } + } } } - ] - }, - { - "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 + } + } + } + } + }, + "202": { + "description": "", + "schema": { + "type": "object" + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" } } + } + } + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/singlesends": { + "post": { + "operationId": "POST_marketing-singlesends", + "summary": "Create Single Send", + "tags": [ + "Single Sends" + ], + "description": "**This endpoint allows you to create a new Single Send.**\n\nPlease note that if you are migrating from the previous version of Single Sends, you no longer need to pass a template ID with your request to this endpoint. Instead, you will pass all template data in the `email_config` object.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/singlesend_request", + "example": { + "name": "Example API Created Single Send", + "categories": [ + "unique opens" + ], + "send_to": { + "all": true + }, + "email_config": { + "design_id": "", + "editor": "design", + "suppression_group_id": 12345, + "sender_id": 1234567 + } + } + } + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/singlesend_response" + }, + "examples": { + "application/json": { + "name": "Example API Created Single Send", + "id": "27c21bbf-a12c-440b-b8bf-c526975328ca", + "status": "scheduled", + "created_at": "2020-05-18T17:28:27.272Z", + "send_at": "2020-06-16T00:19:55.106Z", + "categories": [ + "unique opens" + ], + "email_config": { + "subject": "", + "html_content": "", + "plain_content": "", + "generate_plain_content": true, + "editor": "code", + "suppression_group_id": null, + "custom_unsubscribe_url": null, + "sender_id": null, + "ip_pool": null + }, + "send_to": { + "list_ids": [ + "f2fe66a1-43f3-4e3a-87b1-c6a600d805f0" ] - }, - { - "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 + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" } } - ] - }, - { - "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 + } + } + } + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" } } - ] + } } - ] + } } } }, @@ -15175,125 +15598,67 @@ "Authorization": [] } ] - } - }, - "/browsers/stats": { + }, "get": { - "operationId": "GET_browsers-stats", - "summary": "Retrieve email statistics by browser.", + "operationId": "GET_marketing-singlesends", + "summary": "Get All Single Sends", "tags": [ - "Stats" - ], - "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).", - "produces": [ - "application/json" + "Single Sends" ], + "description": "**This endpoint allows you to retrieve all your Single Sends.**\n\nReturns all of your Single Sends with condensed details about each, including the Single Sends' IDs. For more details about an individual Single Send, pass the Single Send's ID to the `/marketing/singlesends/{id}` endpoint.", "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", + "name": "page_size", "in": "query", - "description": "How to group the stats. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] + "type": "integer" }, { - "name": "browsers", + "name": "page_token", "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" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_clicks" + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/singlesend_response_short" + } + }, + "_metadata": { + "$ref": "#/definitions/_metadata" + } } - }, - "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 + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" }, - "name": "Chrome", - "type": "browser" - }, - { - "metrics": { - "clicks": 1, - "unique_clicks": 1 + "message": { + "type": "string" }, - "name": "Firefox", - "type": "browser" + "error_id": { + "type": "string" + } } - ] + } } - ] + } } } }, @@ -15302,78 +15667,78 @@ "Authorization": [] } ] - } - }, - "/subusers": { - "get": { - "operationId": "GET_subusers", - "summary": "List all Subusers", + }, + "delete": { + "operationId": "DELETE_marketing-singlesends", + "summary": "Bulk Delete Single Sends", "tags": [ - "Subusers API" - ], - "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)", - "produces": [ - "application/json" + "Single Sends" ], + "description": "**This endpoint allows you to delete multiple Single Sends using an array of Single Sends IDs.**\n\nTo first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.\n\nPlease note that a DELETE request is permanent, and your Single Sends will not be recoverable after deletion.", "parameters": [ { - "name": "username", - "in": "query", - "description": "The username of this subuser.", - "type": "string" - }, - { - "name": "limit", - "in": "query", - "description": "The number of results you would like to get in each request.", - "type": "integer" - }, - { - "name": "offset", + "name": "ids", "in": "query", - "description": "The number of subusers to skip.", - "type": "integer" + "description": "Single Send IDs to delete", + "type": "array", + "minItems": 1, + "maxItems": 50, + "items": { + "type": "string" + } } ], "responses": { - "200": { + "204": { + "description": "" + }, + "404": { "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" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } + } } - ] + } } }, - "401": { - "description": "Unexpected error in API call. See HTTP response body for details.", + "500": { + "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } @@ -15383,20 +15748,24 @@ "Authorization": [] } ] - }, + } + }, + "/marketing/singlesends/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], "post": { - "operationId": "POST_subusers", - "summary": "Create Subuser", + "operationId": "POST_marketing-singlesends-id", + "summary": "Duplicate Single Send", "tags": [ - "Subusers API" - ], - "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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Single Sends" ], + "description": "**This endpoint allows you to duplicate an existing Single Send using its Single Send ID.**\n\nDuplicating a Single Send is useful when you want to create a Single Send but don't want to start from scratch. Once duplicated, you can update or edit the Single Send by making a PATCH request to the `/marketing/singlesends/{id}` endpoint.\n \nIf you leave the `name` field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text “Copy of ” prepended to it. The `name` field length is limited to 100 characters, so the end of the new Single Send name, including “Copy of ”, will be trimmed if the name exceeds this limit.", "parameters": [ { "name": "body", @@ -15404,126 +15773,70 @@ "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": { + "name": { "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" - } + "minLength": 1, + "maxLength": 100, + "description": "The name of the duplicate Single Send. If you choose to leave the name field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text 'Copy of ' prepended to it. The end of the new Single Send name, including 'Copy of ', will be trimmed if the name exceeds the character limit." } - }, - "required": [ - "username", - "email", - "password", - "ips" - ], - "example": { - "username": "John@example.com", - "email": "John@example.com", - "password": "johns_password", - "ips": [ - "1.1.1.1", - "2.2.2.2" - ] } } } ], "responses": { - "200": { + "201": { "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" - } - } + "$ref": "#/definitions/singlesend_response" } }, - "400": { + "404": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "username exists" - }, - { - "message": "unable to validate IPs at this time" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } }, - "401": { + "500": { "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" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "unable to validate IPs at this time" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } @@ -15533,102 +15846,102 @@ "Authorization": [] } ] - } - }, - "/subusers/{subuser_name}": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], + }, "patch": { - "operationId": "PATCH_subusers-subuser_name", - "summary": "Enable/disable a subuser", + "operationId": "PATCH_marketing-singlesends-id", + "summary": "Update Single Send", "tags": [ - "Subusers API" - ], - "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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Single Sends" ], + "description": "**This endpoint allows you to update a Single Send using a Single Send ID.**\n\nYou only need to pass the fields you want to update. Any blank/missing fields will remain unaltered.", "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." - } - }, - "example": { - "disabled": false - } + "$ref": "#/definitions/singlesend_request" } } ], "responses": { - "204": { + "202": { "description": "", "schema": { - "type": "object", - "properties": {} + "$ref": "#/definitions/singlesend_response" } }, "400": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid username" - }, - { - "message": "no fields provided" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } }, - "401": { + "404": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } }, "500": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "unable to enable user" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } @@ -15639,46 +15952,82 @@ } ] }, - "delete": { - "operationId": "DELETE_subusers-subuser_name", - "summary": "Delete a subuser", + "get": { + "operationId": "GET_marketing-singlesends-id", + "summary": "Get Single Send by ID", "tags": [ - "Subusers API" + "Single Sends" ], - "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)", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", + "description": "**This endpoint allows you to retrieve details about one Single Send using a Single Send ID.**\n\nYou can retrieve all of your Single Sends by making a GET request to the `/marketing/singlesends` endpoint.", + "responses": { + "200": { + "description": "", "schema": { - "type": "null" + "$ref": "#/definitions/singlesend_response" + }, + "examples": { + "application/json": { + "name": "single-send-1", + "id": "2f6dec81-43b9-4c67-a890-3a38cb63b54a", + "status": "scheduled", + "created_at": "2020-12-13T16:24:42.013Z", + "send_to": { + "segment_ids": [ + "dad84de3-bec4-4e04-b132-2cbfd4bb3789", + "7dce758d-1155-4102-88d2-ca65565ac98b" + ], + "all": true + } + } } - } - ], - "responses": { - "204": { + }, + "404": { "description": "", "schema": { "type": "object", - "properties": {} + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } + } + } + } } }, - "401": { + "500": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } @@ -15688,70 +16037,65 @@ "Authorization": [] } ] - } - }, - "/subusers/{subuser_name}/monitor": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "description": "The name of the subuser for which to retrieve monitor settings.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_subusers-subuser_name-monitor", - "summary": "Retrieve monitor settings for a subuser", + }, + "delete": { + "operationId": "DELETE_marketing-singlesends-id", + "summary": "Delete Single Send by ID", "tags": [ - "Subusers API" - ], - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "produces": [ - "application/json" + "Single Sends" ], + "description": "**This endpoint allows you to delete one Single Send using a Single Send ID.**\n\nTo first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint.\n\nPlease note that a `DELETE` request is permanent, and your Single Send will not be recoverable after deletion.", "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/monitor" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "frequency": 500 - } - } + "204": { + "description": "" }, - "401": { + "404": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } }, - "404": { + "500": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } @@ -15761,29 +16105,41 @@ "Authorization": [] } ] - }, + } + }, + "/marketing/singlesends/search": { "post": { - "operationId": "POST_subusers-subuser_name-monitor", - "summary": "Create monitor settings", + "operationId": "POST_marketing-singlesends-search", + "summary": "Get Single Sends Search", "tags": [ - "Subusers API" - ], - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Single Sends" ], + "description": "**This endpoint allows you to search for Single Sends based on specified criteria.**\n\nYou can search for Single Sends by passing a combination of values using the `name`, `status`, and `categories` request body fields.\n\nFor example, if you want to search for all Single Sends that are \"drafts\" or \"scheduled\" and also associated with the category \"shoes,\" your request body may look like the example below.\n\n```javascript\n{\n \"status\": [\n \"draft\",\n \"scheduled\"\n ],\n \"categories\": [\n \"shoes\"\n ],\n}\n```", "parameters": [ + { + "name": "page_size", + "in": "query", + "type": "integer" + }, + { + "name": "page_token", + "in": "query", + "type": "string" + }, { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/monitor", + "$ref": "#/definitions/singlesend_search", "example": { - "email": "example@example.com", - "frequency": 50000 + "name": "specific-single-send-name", + "status": [ + "draft", + "scheduled" + ], + "categories": [ + "shoes" + ] } } } @@ -15792,44 +16148,66 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/monitor" - }, - "examples": { - "application/json": { - "email": "example@example.com", - "frequency": 50000 + "type": "object", + "properties": { + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/singlesend_response_short" + } + }, + "_metadata": { + "$ref": "#/definitions/_metadata" + } } - } - }, - "400": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" }, "examples": { "application/json": { - "errors": [ + "result": [ { - "field": null, - "message": "User already has a monitor" + "id": "df25ffdf-6a96-458a-9419-6d87d3094c6b", + "name": "single-send-1", + "status": "triggered", + "categories": [ + "shoes" + ], + "is_abtest": true, + "updated_at": "3263-04-09T09:05:08.193Z", + "created_at": "4739-10-29T07:11:32.476Z", + "send_at": "2471-05-31T15:46:18.797Z" } - ] + ], + "_metadata": { + "self": "nwNSrPSWt7d", + "prev": "P0Enoayd", + "next": "DYEsTUDww9-", + "count": 1 + } } } }, - "401": { + "404": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } @@ -15839,75 +16217,121 @@ "Authorization": [] } ] - }, + } + }, + "/marketing/singlesends/{id}/schedule": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], "put": { - "operationId": "PUT_subusers-subuser_name-monitor", - "summary": "Update Monitor Settings for a subuser", + "operationId": "PUT_marketing-singlesends-id-schedule", + "summary": "Schedule Single Send", "tags": [ - "Subusers API" - ], - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Single Sends" ], + "description": "**This endpoint allows you to schedule a Single Send for future delivery using a Single Send ID.**\n\nTo schedule a Single Send, you must pass a date string in ISO 8601 time format (yyyy-MM-ddTHH:mm:ssZ) using the required `send_at` field. For example, the ISO 8601 format for 9:00 AM UTC on May 6, 2020 would be `2020-05-06T09:00:00Z`. You may also pass the string `\"now\"` to send the Single Send immediately.", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/monitor", + "type": "object", + "properties": { + "send_at": { + "type": "string", + "description": "This is the ISO 8601 time at which to send the Single Send; must be in future, or the string \"now\"", + "enum": [ + "now" + ], + "format": "date-time" + } + }, + "required": [ + "send_at" + ], "example": { - "email": "example@example.com", - "frequency": 500 + "send_at": "now" } } } ], "responses": { - "200": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/monitor" + "type": "object", + "properties": { + "send_at": { + "type": "string", + "format": "date-time" + }, + "status": { + "type": "string", + "enum": [ + "scheduled" + ] + } + } }, "examples": { "application/json": { - "email": "example@example.com", - "frequency": 500 + "send_at": "now", + "status": "scheduled" } } }, - "400": { + "404": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": "email", - "message": "Email is required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } }, - "401": { + "500": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } @@ -15919,122 +16343,135 @@ ] }, "delete": { - "operationId": "DELETE_subusers-subuser_name-monitor", - "summary": "Delete monitor settings", + "operationId": "DELETE_marketing-singlesends-id-schedule", + "summary": "Delete Single Send Schedule", "tags": [ - "Subusers API" - ], - "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" - } + "Single Sends" ], + "description": "**This endpoint allows you to cancel a scheduled Single Send using a Single Send ID.**\n\nMaking a DELETE request to this endpoint will cancel the scheduled sending of a Single Send. The request will not delete the Single Send itself. Deleting a Single Send can be done by passing a DELETE request to `/marketing/singlesends/{id}`.", "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "object", - "properties": {} + "$ref": "#/definitions/singlesend_schedule" } }, - "401": { + "404": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } }, - "404": { + "500": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "No monitor settings for this user" + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } } - ] + } } } } - } + }, + "security": [ + { + "Authorization": [] + } + ] } }, - "/subusers/reputations": { + "/marketing/singlesends/categories": { "get": { - "operationId": "GET_subusers-reputations", - "summary": "Retrieve Subuser Reputations", + "operationId": "GET_marketing-singlesends-categories", + "summary": "Get All Categories", "tags": [ - "Subusers API" - ], - "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.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "usernames", - "in": "query", - "type": "string" - } + "Single Sends" ], + "description": "**This endpoint allows you to retrieve all the categories associated with your Single Sends.**\n\nThis endpoint will return your latest 1,000 categories.", "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" + "type": "object", + "properties": { + "categories": { + "type": "array", + "uniqueItems": true, + "maxItems": 1000, + "description": "list of latest one thousand unique categories associated with all Single Sends in ascending order", + "items": { + "type": "string" } - }, - "required": [ - "reputation", - "username" - ] + } } }, "examples": { - "application/json": [ - { - "username": "example_subuser", - "reputation": 99 - }, - { - "username": "example_subuser2", - "reputation": 95.2 + "application/json": { + "categories": [ + "equipment", + "shoes", + "sports" + ] + } + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } + } } - ] + } } } }, @@ -16045,191 +16482,123 @@ ] } }, - "/subusers/{subuser_name}/ips": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], - "put": { - "operationId": "PUT_subusers-subuser_name-ips", - "summary": "Update IPs assigned to a subuser", + "/marketing/test/send_email": { + "post": { + "operationId": "POST_marketing-test-send_email", + "summary": "Send a Test Marketing Email", "tags": [ - "Subusers API" - ], - "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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Send Test Email" ], + "description": "**This endpoint allows you to send a test marketing email to a list of email addresses**.\n\nBefore sending a marketing message, you can test it using this endpoint. You may specify up to **10 contacts** in the `emails` request body field. You must also specify a `template_id` and include either a `from_address` or `sender_id`. You can manage your templates with the [Twilio SendGrid App](https://mc.sendgrid.com/dynamic-templates) or the [Transactional Templates API](https://sendgrid.api-docs.io/v3.0/transactional-templates).\n\n> Please note that this endpoint works with Dynamic Transactional Templates only. Legacy Transactional Templates will not be delivered.\n\nFor more information about managing Dynamic Transactional Templates, see [How to Send Email with Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).\n\nYou can also test your Single Sends in the [Twilio SendGrid Marketing Campaigns UI](https://mc.sendgrid.com/single-sends).", "parameters": [ { "name": "body", "in": "body", - "schema": { - "type": "array", - "description": "The IP addresses you would like to assign to the subuser.", - "items": { - "type": "string", - "format": "ipv4" - }, - "example": [ - "127.0.0.1" - ] - } - }, - { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" - } - ], - "responses": { - "200": { - "description": "", "schema": { "type": "object", "properties": { - "ips": { + "template_id": { + "type": "string", + "format": "uuid", + "description": "The ID of the template that you would like to use. If you use a template that contains a subject and content (either text or HTML), then those values specified at the personalizations or message level will not be used." + }, + "version_id_override": { + "type": "string", + "format": "uuid", + "description": " You can override the active template with an alternative template version by passing the version ID in this field. If this field is blank, the active template version will be used." + }, + "sender_id": { + "type": "integer", + "description": "This ID must belong to a verified sender. Alternatively, you may supply a `from_address` email." + }, + "custom_unsubscribe_url": { + "type": "string", + "description": "A custom unsubscribe URL." + }, + "suppression_group_id": { + "type": "integer" + }, + "emails": { "type": "array", - "description": "The IP addresses that are assigned to the subuser.", + "uniqueItems": true, + "minItems": 1, + "maxItems": 10, "items": { "type": "string", - "format": "ipv4" - } + "format": "email" + }, + "description": "An array of email addresses you want to send the test message to." + }, + "from_address": { + "type": "string", + "description": "You can either specify this address or specify a verified sender ID.", + "format": "email" } - } - }, - "examples": { - "application/json": { - "ips": [ - "127.0.0.1" - ] - } + }, + "required": [ + "template_id", + "emails" + ], + "example": "{\"template_id\":\"f8f77db8-b9fa-4b3c-9ee8-de3d582016b8\",\"version_id_override\":\"\",\"sender_id\":6060664,\"custom_unsubscribe_url\":\"esse Excepteur \",\"suppression_group_id\":21865513,\"emails\":[\"janedoe@example.com\",\"tiramisu@example.com\",\"bundt@example.com\"}" } - }, - "401": { + } + ], + "responses": { + "202": { "description": "", "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + "type": "object" } + }, + "400": { + "$ref": "#/responses/trait:errorResponse:400" } - } + }, + "security": [ + { + "Authorization": [] + } + ] } }, - "/subusers/{subuser_name}/stats/monthly": { - "parameters": [ - { - "name": "subuser_name", - "in": "path", - "required": true, - "type": "string" - } - ], + "/marketing/stats/automations": { "get": { - "operationId": "GET_subusers-subuser_name-stats-monthly", - "summary": "Retrieve the monthly email statistics for a single subuser", + "operationId": "getall-automation-stats", + "summary": "Get All Automation Stats", "tags": [ - "Subusers API" - ], - "description": "**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", - "produces": [ - "application/json" + "Marketing Campaigns Stats" ], + "description": "**This endpoint allows you to retrieve stats for all your Automations.**\n\nBy default, all of your Automations will be returned, but you can specify a selection by passing in a comma-separated list of Automation IDs as the value of the query string parameter `automation_ids`.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", "parameters": [ { - "name": "date", - "in": "query", - "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", - "required": true, - "type": "string" - }, - { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", - "required": false, - "type": "string", - "default": "delivered" - }, - { - "name": "sort_by_direction", + "name": "automation_ids", "in": "query", - "description": "The direction you want to sort.", - "required": false, - "type": "string", - "default": "desc", - "enum": [ - "desc", - "asc" - ] + "description": "This endpoint returns all automation IDs if no `automation_ids` are specified.", + "type": "array", + "minItems": 1, + "maxItems": 25, + "items": { + "type": "string" + } }, { - "name": "limit", - "in": "query", - "description": "Optional field to limit the number of results returned.", - "required": false, - "type": "integer", - "default": 5 + "$ref": "#/parameters/trait:pagination:page_size" }, { - "name": "offset", - "in": "query", - "description": "Optional beginning point in the list to retrieve from.", - "required": false, - "type": "integer", - "default": 0 + "$ref": "#/parameters/trait:pagination:page_token" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/subuser_stats" - }, - "examples": { - "application/json": { - "date": "2016-02-01", - "stats": [ - { - "first_name": "John", - "last_name": "Doe", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 5, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 10, - "processed": 10, - "requests": 10, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "user1", - "type": "subuser" - } - ] - } + "$ref": "#/definitions/automations-response" + } + }, + "400": { + "description": "", + "schema": { + "$ref": "#/definitions/error_schema" } } }, @@ -16240,130 +16609,60 @@ ] } }, - "/subusers/stats/monthly": { + "/marketing/stats/automations/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_subusers-stats-monthly", - "summary": "Retrieve monthly stats for all subusers", + "operationId": "get-automation-stat", + "summary": "Get Automation Stats by ID", "tags": [ - "Subusers API" - ], - "description": "**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**\n\nWhile you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.\n\nFor more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html).", - "produces": [ - "application/json" + "Marketing Campaigns Stats" ], + "description": "**This endpoint allows you to retrieve stats for a single Automation using its ID.**\n\nMultiple Automation IDs can be retrieved using the #endpoint:tMC3DWPZFRZKCx45d endpoint. Once you have an ID, this endpoint will return detailed stats for the single automation specified.\n\nYou may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned.", "parameters": [ { - "name": "date", - "in": "query", - "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", - "required": true, - "type": "string" + "$ref": "#/parameters/trait:automationQueryParams:group_by" }, { - "name": "subuser", - "in": "query", - "description": "A substring search of your subusers.", - "required": false, - "type": "string" + "$ref": "#/parameters/trait:automationQueryParams:step_ids" }, { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", - "required": false, - "type": "string", - "default": "delivered" + "$ref": "#/parameters/trait:baseParams:aggregated_by" }, { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort.", - "required": false, - "type": "string", - "default": "desc", - "enum": [ - "desc", - "asc" - ] + "$ref": "#/parameters/trait:baseParams:start_date" }, { - "name": "limit", - "in": "query", - "description": "Optional field to limit the number of results returned.", - "required": false, - "type": "integer", - "default": 5 + "$ref": "#/parameters/trait:baseParams:end_date" }, { - "name": "offset", - "in": "query", - "description": "Optional beginning point in the list to retrieve from.", - "required": false, - "type": "integer", - "default": 0 + "$ref": "#/parameters/trait:baseParams:timezone" + }, + { + "$ref": "#/parameters/trait:pagination:page_size" + }, + { + "$ref": "#/parameters/trait:pagination:page_token" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/subuser_stats" - }, - "examples": { - "application/json": { - "date": "2016-02-01", - "stats": [ - { - "first_name": "John", - "last_name": "Doe", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 1, - "processed": 0, - "requests": 100, - "spam_report_drops": 0, - "spam_reports": 99, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "user1", - "type": "subuser" - }, - { - "first_name": "Jane", - "last_name": "Doe", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 5, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 10, - "processed": 10, - "requests": 10, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "user2", - "type": "subuser" - } - ] - } + "$ref": "#/definitions/automations-response" } + }, + "400": { + "$ref": "#/responses/trait:errorResponse:400" + }, + "404": { + "description": "" } }, "security": [ @@ -16373,88 +16672,102 @@ ] } }, - "/subusers/stats/sums": { + "/marketing/stats/singlesends": { "get": { - "operationId": "GET_subusers-stats-sums", - "summary": " Retrieve the totals for each email statistic metric for all subusers.", + "operationId": "getall-singlesend-stats", + "summary": "Get All Single Sends Stats", "tags": [ - "Subusers API" - ], - "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).", - "produces": [ - "application/json" + "Marketing Campaigns Stats" ], + "description": "**This endpoint allows you to retrieve stats for all your Single Sends.**\n\nBy default, all of your Single Sends will be returned, but you can specify a selection by passing in a comma-separated list of Single Send IDs as the value of the query string parameter `singlesend_ids`.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", "parameters": [ { - "name": "sort_by_direction", - "in": "query", - "description": "The direction you want to sort. ", - "required": false, - "type": "string", - "default": "desc", - "enum": [ - "desc", - "asc" - ] - }, - { - "name": "start_date", + "name": "singlesend_ids", "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" + "description": "This endpoint returns all Single Send IDs if no IDs are included in `singlesend_ids`.", + "type": "array", + "minItems": 1, + "maxItems": 25, + "items": { + "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" + "$ref": "#/parameters/trait:pagination:page_size" }, { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "required": false, - "type": "integer", - "default": 5 + "$ref": "#/parameters/trait:pagination:page_token" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/singlesends-response" + } }, + "400": { + "$ref": "#/responses/trait:errorResponse:400" + } + }, + "security": [ { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results from.", - "required": false, - "type": "integer", - "default": 0 + "Authorization": [] + } + ] + } + }, + "/marketing/stats/singlesends/{id}": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "get-singlesend-stat", + "summary": "Get Single Send Stats by ID", + "tags": [ + "Marketing Campaigns Stats" + ], + "description": "**This endpoint allows you to retrieve stats for an individual Single Send using a Single Send ID.**\n\nMultiple Single Send IDs can be retrieved using the #endpoint:CkrCH9JrWPiySTTuu endpoint. Once you have an ID, this endpoint will return detailed stats for the Single Send specified.\n\nYou may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned.", + "parameters": [ + { + "$ref": "#/parameters/trait:baseParams:aggregated_by" }, { - "name": "aggregated_by", - "in": "query", - "description": "How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.", - "required": false, - "type": "string" + "$ref": "#/parameters/trait:baseParams:start_date" }, { - "name": "sort_by_metric", - "in": "query", - "description": "The metric that you want to sort by. Must be a single metric.", - "required": false, - "type": "string", - "default": "delivered" + "$ref": "#/parameters/trait:baseParams:end_date" + }, + { + "$ref": "#/parameters/trait:baseParams:timezone" + }, + { + "$ref": "#/parameters/trait:pagination:page_size" + }, + { + "$ref": "#/parameters/trait:pagination:page_token" + }, + { + "$ref": "#/parameters/trait:singlesendQueryParams:group_by" } ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/category_stats" - }, - "examples": { - "application/json": { - "date": "2015-10-11", - "stats": [] - } + "$ref": "#/definitions/singlesends-response" } + }, + "400": { + "$ref": "#/responses/trait:errorResponse:400" + }, + "404": { + "description": "" } }, "security": [ @@ -16464,346 +16777,201 @@ ] } }, - "/subusers/stats": { + "/marketing/stats/automations/{id}/links": { + "parameters": [ + { + "name": "id", + "in": "path", + "description": "The ID of the Automation you want to get click tracking stats for. ", + "required": true, + "type": "string", + "format": "uuid" + } + ], "get": { - "operationId": "GET_subusers-stats", - "summary": "Retrieve email statistics for your subusers.", + "operationId": "get-automation-link-stat", + "summary": "Get Automation Click Tracking Stats by ID", "tags": [ - "Subusers API" + "Marketing Campaigns Stats" ], - "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).", - "produces": [ - "application/json" + "description": "**This endpoint lets you retrieve click-tracking stats for a single Automation**.\n\nThe stats returned list the URLs embedded in your Automation and the number of clicks each one received.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", + "parameters": [ + { + "$ref": "#/parameters/trait:automationQueryParams:group_by" + }, + { + "$ref": "#/parameters/trait:automationQueryParams:step_ids" + }, + { + "$ref": "#/parameters/trait:pagination:page_size" + }, + { + "$ref": "#/parameters/trait:pagination:page_token" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/automations-link-stats-response" + } + }, + "400": { + "$ref": "#/responses/trait:errorResponse:400" + }, + "404": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/stats/singlesends/{id}/links": { + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "get-singlesend-link-stat", + "summary": "Get Single Send Click Tracking Stats by ID", + "tags": [ + "Marketing Campaigns Stats" ], + "description": "**This endpoint lets you retrieve click-tracking stats for one Single Send**.\n\nThe stats returned list the URLs embedded in the specified Single Send and the number of clicks each one received.\n\nResponses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100.\n\nYou can retrieve a specific page of responses with the `page_token` query string parameter.", "parameters": [ { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "required": false, - "type": "integer" + "$ref": "#/parameters/trait:pagination:page_size" }, { - "name": "offset", - "in": "query", - "description": "The point in the list to begin retrieving results from.", - "required": false, - "type": "integer" + "$ref": "#/parameters/trait:pagination:page_token" }, { - "name": "aggregated_by", + "$ref": "#/parameters/trait:singlesendQueryParams2:group_by" + }, + { + "$ref": "#/parameters/trait:singlesendQueryParams2:ab_variation_id" + }, + { + "$ref": "#/parameters/trait:singlesendQueryParams2:ab_phase_id" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/singlesends-link-stats-response" + } + }, + "400": { + "$ref": "#/responses/trait:errorResponse:400" + }, + "404": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/marketing/stats/singlesends/export": { + "get": { + "operationId": "get-singlesend-stats-export", + "summary": "Export Single Send Stats", + "tags": [ + "Marketing Campaigns Stats" + ], + "description": "**This endpoint allows you to export Single Send stats as .CSV data**.\n\nYou can specify one Single Send or many: include as many Single Send IDs as you need, separating them with commas, as the value of the `ids` query string paramter.\n\nThe data is returned as plain text response but in .CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a .csv file.", + "parameters": [ + { + "name": "ids", "in": "query", - "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] + "description": "The IDs of Single Sends for which to export stats.", + "type": "array", + "minItems": 1, + "maxItems": 50, + "items": { + "type": "string" + } }, { - "name": "subusers", + "name": "timezone", "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" + "description": "The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented; i.e. `\"America/Chicago\"`. This parameter changes the timezone format only; it does not alter which stats are returned.", + "type": "string", + "default": "UTC" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "string", + "description": "CSV data" + } }, + "400": { + "description": "" + } + }, + "security": [ { - "name": "start_date", + "Authorization": [] + } + ] + } + }, + "/marketing/stats/automations/export": { + "get": { + "operationId": "get-automations-stats-export", + "summary": "Export Automation Stats", + "tags": [ + "Marketing Campaigns Stats" + ], + "description": "**This endpoint allows you to export Automation stats as CSV data**.\n\nYou can specify one Automation or many: include as many Automation IDs as you need, separating them with commas, as the value of the `ids` query string paramter.\n\nThe data is returned as plain text response but in CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a `.csv` file.", + "parameters": [ + { + "name": "ids", "in": "query", - "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", - "required": true, - "type": "string" + "description": "The IDs of Automations for which to export stats.", + "type": "array", + "minItems": 1, + "maxItems": 50, + "items": { + "type": "string" + } }, { - "name": "end_date", + "name": "timezone", "in": "query", - "description": "The end date of the statistics to retrieve. Defaults to today.", - "required": false, - "type": "string" + "description": "The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented; i.e. `\"America/Chicago\"`. This parameter changes the timezone format only; it does not alter which stats are returned.", + "type": "string", + "default": "UTC" } ], "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 - } - } - ] - } - ] + "type": "string", + "description": "CSV data" } + }, + "400": { + "description": "" } }, "security": [ @@ -16813,104 +16981,14 @@ ] } }, - "/suppression/unsubscribes": { - "get": { - "operationId": "GET_suppression-unsubscribes", - "summary": "Retrieve all global suppressions", + "/senders": { + "post": { + "operationId": "POST_senders", + "summary": "Create a Sender Identity", "tags": [ - "Suppressions - Global Suppressions" - ], - "description": "**This endpoint allows you to retrieve a list of all email address that are globally suppressed.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "start_time", - "in": "query", - "description": "Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive).", - "type": "integer" - }, - { - "name": "end_time", - "in": "query", - "description": "Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive).", - "type": "integer" - }, - { - "name": "limit", - "in": "query", - "description": "The number of results to display on each page.", - "type": "integer" - }, - { - "name": "offset", - "in": "query", - "description": "The point in the list of results to begin displaying global suppressions.", - "type": "integer" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "created": { - "type": "integer", - "description": "A Unix timestamp indicating when the recipient was added to the global suppression list." - }, - "email": { - "type": "string", - "description": "The email address of the recipient who is globally suppressed." - } - }, - "required": [ - "created", - "email" - ] - } - }, - "examples": { - "application/json": [ - { - "created": 1443651141, - "email": "user1@example.com" - }, - { - "created": 1443651154, - "email": "user2@example.com" - } - ] - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/suppressions/global": { - "post": { - "operationId": "POST_asm-suppressions-global", - "summary": "Add recipient addresses to the global suppression group.", - "tags": [ - "Suppressions - Global Suppressions" - ], - "description": "**This endpoint allows you to add one or more email addresses to the global suppressions group.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Sender Identities API" ], + "description": "**This endpoint allows you to create a new sender identity.**\n\n*You may create up to 100 unique sender identities.*\n\nSender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", "parameters": [ { "name": "body", @@ -16918,19 +16996,89 @@ "schema": { "type": "object", "properties": { - "recipient_emails": { - "type": "array", - "description": "The email address, or addresses, that you want to add to the global suppressions group.", - "items": { - "type": "string" - } + "nickname": { + "type": "string", + "description": "A nickname for the sender identity. Not used for sending." + }, + "from": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is where the email will appear to originate from for your recipient" + }, + "name": { + "type": "string", + "description": "This is the name appended to the from email field. IE - Your name or company name." + } + }, + "required": [ + "email" + ] + }, + "reply_to": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is the email that your recipient will reply to." + }, + "name": { + "type": "string", + "description": "This is the name appended to the reply to email field. IE - Your name or company name." + } + }, + "required": [ + "email" + ] + }, + "address": { + "type": "string", + "description": "The physical address of the sender identity." + }, + "address_2": { + "type": "string", + "description": "Additional sender identity address information." + }, + "city": { + "type": "string", + "description": "The city of the sender identity." + }, + "state": { + "type": "string", + "description": "The state of the sender identity." + }, + "zip": { + "type": "string", + "description": "The zipcode of the sender identity." + }, + "country": { + "type": "string", + "description": "The country of the sender identity." } }, + "required": [ + "nickname", + "address", + "city", + "country" + ], "example": { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" - ] + "nickname": "My Sender ID", + "from": { + "email": "from@example.com", + "name": "Example INC" + }, + "reply_to": { + "email": "replyto@example.com", + "name": "Example INC" + }, + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "state": "Colorado", + "zip": "80202", + "country": "United States" } } }, @@ -16940,27 +17088,107 @@ ], "responses": { "201": { + "description": "", + "schema": { + "$ref": "#/definitions/senderID" + }, + "examples": { + "application/json": { + "id": 1, + "nickname": "My Sender ID", + "from": { + "email": "from@example.com", + "name": "Example INC" + }, + "reply_to": { + "email": "replyto@example.com", + "name": "Example INC" + }, + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "state": "Colorado", + "zip": "80202", + "country": "United States", + "verified": true, + "updated_at": 1449872165, + "created_at": 1449872165, + "locked": false + } + } + }, + "400": { "description": "", "schema": { "type": "object", "properties": { - "recipient_emails": { + "errors": { "type": "array", - "description": "The email addresses that are globally suppressed", "items": { - "type": "string" + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } } - }, - "required": [ - "recipient_emails" - ] + } }, "examples": { "application/json": { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" + "errors": [ + { + "message": "The JSON you have submitted cannot be parsed.", + "field": "" + }, + { + "message": "You've reached your limit of 100 sender identities. Please delete one or more and try again.", + "field": "" + }, + { + "message": "nickname is required.", + "field": "nickname" + }, + { + "message": "You already have a sender identity with the same nickname.", + "field": "nickname" + }, + { + "message": "from_name is required.", + "field": "from_name" + }, + { + "message": "from_email is required.", + "field": "from_email" + }, + { + "message": "From email is not a valid email address.", + "field": "from_email" + }, + { + "message": "reply_to is required.", + "field": "reply_to" + }, + { + "message": "Reply to email is not a valid email address.", + "field": "reply_to" + }, + { + "message": "address is required.", + "field": "address" + }, + { + "message": "city is required.", + "field": "city" + }, + { + "message": "country is required.", + "field": "country" + } ] } } @@ -16971,28 +17199,14 @@ "Authorization": [] } ] - } - }, - "/asm/suppressions/global/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.", - "required": true, - "type": "string" - } - ], + }, "get": { - "operationId": "GET_asm-suppressions-global-email", - "summary": "Retrieve a Global Suppression", + "operationId": "GET_v3-senders", + "summary": "Get all Sender Identities", "tags": [ - "Suppressions - Global Suppressions" - ], - "description": "**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**\n\nIf the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", - "produces": [ - "application/json" + "Sender Identities API" ], + "description": "**This endpoint allows you to retrieve a list of all sender identities that have been created for your account.**\n\nSender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -17002,50 +17216,43 @@ "200": { "description": "", "schema": { - "title": "Retrieve a Global Suppression response", "type": "object", "properties": { - "recipient_email": { - "type": "string", - "description": "The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed." + "result": { + "type": "array", + "items": { + "$ref": "#/definitions/senderID" + } } - }, - "required": [ - "recipient_email" - ] - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "operationId": "DELETE_asm-suppressions-global-email", - "summary": "Delete a Global Suppression", - "tags": [ - "Suppressions - Global Suppressions" - ], - "description": "**This endpoint allows you to remove an email address from the global suppressions group.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" + } + }, + "examples": { + "application/json": { + "result": [ + { + "id": 1, + "nickname": "My Sender ID", + "from": { + "email": "from@example.com", + "name": "Example INC" + }, + "reply_to": { + "email": "replyto@example.com", + "name": "Example INC" + }, + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "state": "Colorado", + "zip": "80202", + "country": "United States", + "verified": true, + "updated_at": 1449872165, + "created_at": 1449872165, + "locked": false + } + ] + } } } }, @@ -17056,29 +17263,23 @@ ] } }, - "/asm/groups/{group_id}/suppressions": { + "/senders/{sender_id}": { "parameters": [ { - "name": "group_id", + "name": "sender_id", "in": "path", - "description": "The id of the unsubscribe group that you are adding suppressions to.", + "description": "The ID of the sender identity that you want to update.", "required": true, - "type": "string" + "type": "integer" } ], - "post": { - "operationId": "POST_asm-groups-group_id-suppressions", - "summary": "Add suppressions to a suppression group", + "patch": { + "operationId": "PATCH_v3-senders-sender_id", + "summary": "Update a Sender Identity", "tags": [ - "Suppressions - Suppressions" - ], - "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.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Sender Identities API" ], + "description": "**This endpoint allows you to update a sender identity.**\n\nUpdates to `from.email` require re-verification. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`.\n\nPartial updates are allowed, but fields that are marked as \"required\" in the POST (create) endpoint must not be nil if that field is included in the PATCH request.", "parameters": [ { "name": "body", @@ -17086,22 +17287,77 @@ "schema": { "type": "object", "properties": { - "recipient_emails": { - "type": "array", - "description": "The email address that you want to add to the unsubscribe group.", - "items": { - "type": "string" + "nickname": { + "type": "string", + "description": "A nickname for the sender identity. Not used for sending." + }, + "from": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is where the email will appear to originate from for your recipient" + }, + "name": { + "type": "string", + "description": "This is the name appended to the from email field. IE - Your name or company name." + } + } + }, + "reply_to": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is the email that your recipient will reply to." + }, + "name": { + "type": "string", + "description": "This is the name appended to the reply to email field. IE - Your name or company name." + } } + }, + "address": { + "type": "string", + "description": "The physical address of the sender identity." + }, + "address_2": { + "type": "string", + "description": "Additional sender identity address information." + }, + "city": { + "type": "string", + "description": "The city of the sender identity." + }, + "state": { + "type": "string", + "description": "The state of the sender identity." + }, + "zip": { + "type": "string", + "description": "The zipcode of the sender identity." + }, + "country": { + "type": "string", + "description": "The country of the sender identity." } }, - "required": [ - "recipient_emails" - ], "example": { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" - ] + "nickname": "My Sender ID", + "from": { + "email": "from@example.com", + "name": "Example INC" + }, + "reply_to": { + "email": "replyto@example.com", + "name": "Example INC" + }, + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "state": "Colorado", + "zip": "80202", + "country": "United States" } } }, @@ -17110,49 +17366,277 @@ } ], "responses": { - "201": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/senderID" + }, + "examples": { + "application/json": { + "id": 1, + "nickname": "My Sender ID", + "from": { + "email": "from@example.com", + "name": "Example INC" + }, + "reply_to": { + "email": "replyto@example.com", + "name": "Example INC" + }, + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "state": "Colorado", + "zip": "80202", + "country": "United States", + "verified": true, + "updated_at": 1449872165, + "created_at": 1449872165, + "locked": false + } + } + }, + "400": { "description": "", "schema": { "type": "object", "properties": { - "recipient_emails": { + "errors": { "type": "array", - "description": "The email address that were added to the suppressions list.", "items": { - "type": "string" + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } } } - }, - "required": [ - "recipient_emails" - ] + } }, "examples": { "application/json": { - "recipient_emails": [ - "test1@example.com", - "test2@example.com" - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "get": { - "operationId": "GET_asm-groups-group_id-suppressions", - "summary": "Retrieve all suppressions for a suppression group", - "tags": [ - "Suppressions - Suppressions" + "errors": [ + { + "message": "The JSON you have submitted cannot be parsed.", + "field": "" + }, + { + "message": "nickname is required.", + "field": "nickname" + }, + { + "message": "You already have a sender identity with the same nickname.", + "field": "nickname" + }, + { + "message": "from_name is required.", + "field": "from_name" + }, + { + "message": "from_email is required.", + "field": "from_email" + }, + { + "message": "From email is not a valid email address.", + "field": "from_email" + }, + { + "message": "reply_to is required.", + "field": "reply_to" + }, + { + "message": "Reply to email is not a valid email address.", + "field": "reply_to" + }, + { + "message": "address is required.", + "field": "address" + }, + { + "message": "city is required.", + "field": "city" + }, + { + "message": "country is required.", + "field": "country" + } + ] + } + } + }, + "403": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "You may only update a sender identity when it is unlocked.", + "field": "locked" + } + ] + } + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "resource not found", + "field": "id" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_v3-senders-sender_id", + "summary": "Delete a Sender Identity", + "tags": [ + "Sender Identities API" ], - "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.", - "produces": [ - "application/json" + "description": "**This endoint allows you to delete one of your sender identities.**\n\nSender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + }, + "403": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "You may only delete a sender identity when it is unlocked.", + "field": "locked" + } + ] + } + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "resource not found", + "field": "id" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_v3-senders-sender_id", + "summary": "View a Sender Identity", + "tags": [ + "Sender Identities API" ], + "description": "**This endpoint allows you to retrieve a specific sender identity.**\n\nSender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -17162,92 +17646,9067 @@ "200": { "description": "", "schema": { - "type": "array", - "description": "The list of email addresses belonging to the given suppression group.", - "items": { - "type": "string" - } + "$ref": "#/definitions/senderID" }, "examples": { - "application/json": [ - "example@example.com", - "example2@example.com" + "application/json": { + "id": 1, + "nickname": "My Sender ID", + "from": { + "email": "from@example.com", + "name": "Example INC" + }, + "reply_to": { + "email": "replyto@example.com", + "name": "Example INC" + }, + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "state": "Colorado", + "zip": "80202", + "country": "United States", + "verified": true, + "updated_at": 1449872165, + "created_at": 1449872165, + "locked": false + } + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "resource not found", + "field": "id" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/senders/{sender_id}/resend_verification": { + "parameters": [ + { + "name": "sender_id", + "in": "path", + "description": "The ID of the sender identity for which you would like to resend a verification email.", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_v3-senders-sender_id-resend_verification", + "summary": "Resend Sender Identity Verification", + "tags": [ + "Sender Identities API" + ], + "description": "**This enpdoint allows you to resend a sender identity verification email.**\n\nSender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "The Sender Identity is already verified. No email sent.", + "field": "" + } + ] + } + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "resource not found", + "field": "id" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/lists": { + "post": { + "operationId": "POST_contactdb-lists", + "summary": "Create a List", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to create a list for your recipients.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "title": "Create a List request", + "type": "object", + "properties": { + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "example": { + "name": "your list name" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_contactdb-lists", + "summary": "Retrieve all lists", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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 + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_contactdb-lists", + "summary": "Delete Multiple lists", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to delete multiple recipient lists.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "array", + "items": { + "type": "integer" + }, + "example": [ + 1, + 2, + 3, + 4 + ] + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "400": { + "description": "\"id\" : \"Returned if all list ids are not valid\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "list id was invalid" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/lists/{list_id}": { + "parameters": [ + { + "name": "list_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_contactdb-lists-list_id", + "summary": "Retrieve a single list", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to retrieve a single recipient list.**", + "parameters": [ + { + "name": "list_id", + "in": "query", + "description": "The ID of the list to retrieve.", + "type": "integer" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "List ID does not exist" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_contactdb-lists-list_id", + "summary": "Update a List", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to update the name of one of your recipient lists.**", + "parameters": [ + { + "name": "list_id", + "in": "query", + "description": "The ID of the list you are updating.", + "required": true, + "type": "integer" + }, + { + "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" + ], + "example": { + "name": "newlistname" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the list" + }, + "name": { + "type": "string", + "description": "The new name for the list" + }, + "recipient_count": { + "type": "integer", + "description": "The number of recipients on the list" + } + } + }, + "examples": { + "application/json": { + "id": 1234, + "name": "2016 iPhone Users", + "recipient_count": 0 + } + } + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "List ID does not exist" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_contactdb-lists-list_id", + "summary": "Delete a List", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to delete a specific recipient list with the given ID.**", + "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 + ] + }, + { + "name": "body", + "in": "body", + "schema": { + "type": "null" + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"list_id\" : \"Returned if list_id does not exist\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "List not found: 5" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/lists/{list_id}/recipients": { + "parameters": [ + { + "name": "list_id", + "in": "path", + "description": "The id of the list of recipients you want to retrieve.", + "required": true, + "type": "integer" + } + ], + "get": { + "operationId": "GET_contactdb-lists-list_id-recipients", + "summary": "Retrieve all recipients on a List", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to retrieve all recipients on the list with the given ID.**", + "parameters": [ + { + "name": "page", + "in": "query", + "description": "Page index of first recipient to return (must be a positive integer)", + "required": false, + "type": "integer" + }, + { + "name": "page_size", + "in": "query", + "description": "Number of recipients to return at a time (must be a positive integer between 1 and 1000)", + "required": false, + "type": "integer" + }, + { + "name": "list_id", + "in": "query", + "description": "The ID of the list whose recipients you are requesting.", + "required": true, + "type": "integer" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "list_id", + "message": "Returned if list_id is invalid" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "post": { + "operationId": "POST_contactdb-lists-list_id-recipients", + "summary": "Add Multiple Recipients to a List", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to add multiple recipients to a list.**\n\nAdds 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.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "recipient_id1", + "recipient_id2" + ] + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"list_id\": \"Returned if list_id does not exist\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "list_id", + "message": "list_id does not exist" + }, + { + "field": "recipient_id", + "message": "recipient_id does not exist" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/lists/{list_id}/recipients/{recipient_id}": { + "parameters": [ + { + "name": "list_id", + "in": "path", + "description": "The ID of the list that you want to add the recipient to.", + "required": true, + "type": "integer" + }, + { + "name": "recipient_id", + "in": "path", + "description": "The ID of the recipient you are adding to the list.", + "required": true, + "type": "string" + } + ], + "post": { + "operationId": "POST_contactdb-lists-list_id-recipients-recipient_id", + "summary": "Add a Single Recipient to a List", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to add a single recipient to a list.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_contactdb-lists-list_id-recipients-recipient_id", + "summary": "Delete a Single Recipient from a Single List", + "tags": [ + "Contacts API - Lists" + ], + "description": "**This endpoint allows you to delete a single recipient from a list.**", + "parameters": [ + { + "name": "list_id", + "in": "query", + "description": "The ID of the list you are taking this recipient away from.", + "required": true, + "type": "integer" + }, + { + "name": "recipient_id", + "in": "query", + "description": "The ID of the recipient to take off the list.", + "required": true, + "type": "integer" + }, + { + "name": "body", + "in": "body", + "schema": { + "type": "null" + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/recipients": { + "post": { + "operationId": "POST_contactdb-recipients", + "summary": "Add recipients", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to add a Marketing Campaigns recipient.**\n\nYou 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 rate limit is three requests every 2 seconds. You can upload 1000 contacts per request. So the maximum upload rate is 1500 recipients per second.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address of the recipient.", + "format": "email" + }, + "first_name": { + "type": "string", + "description": "The first name of the recipient." + }, + "last_name": { + "type": "string", + "description": "The last name of the recipient." + }, + "age": { + "type": "integer" + } + }, + "required": [ + "email" + ] + }, + "example": [ + { + "email": "example@example.com", + "first_name": "", + "last_name": "User", + "age": 25 + }, + { + "email": "example2@example.com", + "first_name": "Example", + "last_name": "User", + "age": 25 + } + ] + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "Request body is not valid json" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_contactdb-recipients", + "summary": "Update Recipient", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to update one or more recipients.**\n\nThe body of an API call to this endpoint must include an array of one or more 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.", + "parameters": [ + { + "name": "body", + "in": "body", + "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." + } + }, + "required": [ + "email" + ] + }, + "example": [ + { + "email": "jones@example.com", + "last_name": "Jones", + "first_name": "Guy" + } + ] + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/contactdb_recipient_response" + } + }, + "400": { + "description": "\"\" : \"Returned if request body is not valid json\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "Request body is not valid json" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_contactdb-recipients", + "summary": "Delete Recipients", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to deletes one or more recipients.**\n\nThe body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "recipient_id1", + "recipient_id2" + ] + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object" + } + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "No recipient ids provided" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_contactdb-recipients", + "summary": "Retrieve recipients", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to retrieve all of your Marketing Campaigns recipients.**\n\nBatch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of\nthe list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved.", + "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" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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\"", + "schema": { + "type": "object" + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/status": { + "get": { + "operationId": "GET_contactdb-status", + "summary": "Get Recipient Upload Status", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to check the upload status of a Marketing Campaigns recipient.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "status": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "default": "", + "description": "Valid values are \"worker_delay\" and \"worker_delay_seconds\" (the second value appears only if \"worker_delay\" has a value of \"delayed\")." + }, + "value": { + "type": "string", + "default": "", + "description": "Valid values for the ID \"worker_delay\" are \"OK\" or \"Delayed\". Valid values for the ID \"worker_delay_seconds\" is the time of delay to upload." + }, + "": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "status": [ + { + "id": "worker_delay", + "value": "delayed" + }, + { + "id": "worker_delay_seconds", + "value": "75.0" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/recipients/{recipient_id}": { + "parameters": [ + { + "name": "recipient_id", + "in": "path", + "description": "The ID of the recipient that you want to retrieve.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_contactdb-recipients-recipient_id", + "summary": "Retrieve a single recipient", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to retrieve a single recipient by ID from your contact database.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/contactdb_recipient" + } + }, + "400": { + "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", + "schema": { + "type": "object" + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"recipient_id\" : \"Returned if record for recipient id does not exist\"", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_contactdb-recipients-recipient_id", + "summary": "Delete a Recipient", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to delete a single recipient with the given ID from your contact database.**\n\n> Use this to permanently delete your recipients from all of your contact lists and all segments if required by applicable law.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" + } + }, + "400": { + "description": "\"recipient_id\" : \"Returned if recipient_id is not valid\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "recipient not found" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "recipient_id is not valid" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/recipients/{recipient_id}/lists": { + "parameters": [ + { + "name": "recipient_id", + "in": "path", + "description": "The ID of the recipient for whom you are retrieving lists.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_contactdb-recipients-recipient_id-lists", + "summary": "Retrieve the lists that a recipient is on", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to retrieve the lists that a given recipient belongs to.**\n\nEach recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "recipient ID is invalid" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "recipient id not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/recipients/billable_count": { + "get": { + "operationId": "GET_contactdb-recipients-billable_count", + "summary": "Retrieve the count of billable recipients", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**\n\nYou are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/contactdb_recipient_count" + }, + "examples": { + "application/json": { + "recipient_count": 1234 + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/recipients/count": { + "get": { + "operationId": "GET_contactdb-recipients-count", + "summary": "Retrieve a Count of Recipients", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/contactdb_recipient_count" + }, + "examples": { + "application/json": { + "recipient_count": 1234 + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/recipients/search": { + "get": { + "operationId": "GET_contactdb-recipients-search", + "summary": "Search recipients", + "tags": [ + "Contacts API - Recipients" + ], + "description": "**This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.**\n\nfield_name:\n\n* is a variable that is substituted for your actual custom field name from your recipient.\n* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200)\n* If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert\nyour epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to\nMon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through\nMon, 02 Feb 2015 23:59:59 GMT.", + "parameters": [ + { + "name": "{field_name}", + "in": "query", + "type": "string" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "post": { + "operationId": "POST_contactdb-recipients-search", + "summary": "Search recipients", + "tags": [ + "Contacts API - Recipients" + ], + "description": "

\n Search using segment conditions without actually creating a segment.\n Body contains a JSON object with conditions, a list of conditions as described below, and an optional list_id, which is a valid list ID for a list to limit the search on.\n

\n\n

\n Valid operators for create and update depend on the type of the field for which you are searching.\n

\n\n
    \n
  • Dates:\n
      \n
    • \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n
        \n
      • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
        • \n
      \n
      • \n
    • \"empty\", \"not_empty\"
      • \n
    • \"is within\"\n \n
      • \n
    \n
    • \n
  • Text: \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value), \"empty\", \"not_empty\"
    • \n
  • Numbers: \"eq\", \"lt\", \"gt\", \"empty\", \"not_empty\"
    • \n
  • Email Clicks and Opens: \"eq\" (opened), \"ne\" (not opened)
    • \n
\n\n

\n Field values must all be a string.\n

\n\n

\n Search conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either clicks.campaign_identifier or opens.campaign_identifier.\n The condition value should be a string containing the id of a completed campaign.\n

\n\n

\n Search conditions list may contain multiple conditions, joined by an \"and\" or \"or\" in the \"and_or\" field.\n The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n

", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "list_id": { + "type": "integer", + "format": "int32" + }, + "conditions": { + "type": "array", + "items": { + "and_or": "", + "field": "birthday", + "value": "01/12/1985", + "operator": "eq" + } + } + }, + "required": [ + "list_id", + "conditions" + ], + "example": { + "list_id": -27497588, + "conditions": [ + { + "and_or": "", + "field": "birthday", + "value": "01/12/1985", + "operator": "eq" + }, + { + "and_or": "", + "field": "birthday", + "value": "01/12/1985", + "operator": "eq" + }, + { + "and_or": "", + "field": "birthday", + "value": "01/12/1985", + "operator": "eq" + }, + { + "and_or": "", + "field": "birthday", + "value": "01/12/1985", + "operator": "eq" + } + ] + } + } + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "recipients": { + "type": "array", + "items": { + "type": "object", + "properties": { + "created_at": { + "type": "integer" + }, + "email": { + "type": "string" + }, + "id": { + "type": "string" + }, + "last_emailed": { + "type": "integer" + }, + "last_clicked": { + "type": "integer" + }, + "last_opened": { + "type": "integer" + }, + "custom_fields": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "name": { + "type": "string" + }, + "value": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "string" + } + ] + }, + "type": { + "type": "string" + } + } + } + }, + "updated_at": { + "type": "integer" + }, + "first_name": { + "type": "string" + } + } + } + }, + "recipient_count": { + "type": "integer" + } + } + }, + "examples": { + "application/json": { + "recipients": [ + { + "created_at": -27901208, + "email": "ut magna quis ipsum", + "id": "fugiat ad adipisicing ullamco", + "last_emailed": 21626657 + }, + { + "created_at": 17466400, + "email": "sunt irure", + "id": "et", + "last_clicked": -23135244, + "last_opened": -44593357, + "first_name": "est" + }, + { + "created_at": -34495329, + "email": "reprehenderit incididunt velit Lorem esse", + "id": "esse Ut ad dolore", + "last_clicked": 10164083, + "last_opened": 34443062 + }, + { + "created_at": -37030673, + "email": "amet deserunt fugiat voluptate", + "id": "et exercitation commodo id laborum", + "last_clicked": -10497425 + }, + { + "created_at": 3658435, + "email": "labore veniam", + "id": "ad pariatur esse", + "last_opened": -84227501, + "custom_fields": [ + { + "id": -5765608, + "name": "proident pariatur", + "value": "do in magna mollit", + "type": "dolore ut" + }, + { + "id": -31131201, + "name": "laborum mollit", + "value": 84434696, + "type": "veniam" + } + ], + "updated_at": -56455352, + "first_name": "Ut cupidatat nulla deserunt adipisicing", + "last_clicked": -52862671 + } + ], + "recipient_count": 65190677 + } + } + }, + "400": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/custom_fields": { + "post": { + "operationId": "POST_contactdb-custom_fields", + "summary": "Create a Custom Field", + "tags": [ + "Contacts API - Custom Fields" + ], + "description": "**This endpoint allows you to create a custom field.**\n\n**You can create up to 120 custom fields.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "type": { + "type": "string" + } + }, + "example": { + "name": "pet", + "type": "text" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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\"", + "schema": { + "$ref": "#/definitions/error_schema" + }, + "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" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_contactdb-custom_fields", + "summary": "Retrieve all custom fields", + "tags": [ + "Contacts API - Custom Fields" + ], + "description": "**This endpoint allows you to retrieve all custom fields.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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": { + "custom_fields": [ + { + "id": 6234, + "name": "age", + "type": "number" + }, + { + "id": 6233, + "name": "country", + "type": "text" + }, + { + "id": 6235, + "name": "favorite_color", + "type": "text" + }, + { + "id": 6239, + "name": "fname", + "type": "text" + }, + { + "id": 6240, + "name": "lname", + "type": "text" + }, + { + "id": 49439, + "name": "pet", + "type": "text" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/custom_fields/{custom_field_id}": { + "parameters": [ + { + "name": "custom_field_id", + "in": "path", + "description": "The ID of the custom field that you want to retrieve.", + "required": true, + "type": "integer" + } + ], + "get": { + "operationId": "GET_contactdb-custom_fields-custom_field_id", + "summary": "Retrieve a Custom Field", + "tags": [ + "Contacts API - Custom Fields" + ], + "description": "**This endpoint allows you to retrieve a custom field by ID.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid id" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "Custom field ID does not exist" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_contactdb-custom_fields-custom_field_id", + "summary": "Delete a Custom Field", + "tags": [ + "Contacts API - Custom Fields" + ], + "description": "**This endpoint allows you to delete a custom field by ID.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "202": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "message": "Custom Field delete is processing." + } + } + }, + "400": { + "description": "\"id\" : \"Returned if custom_field_id is not valid\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "Custom field ID does not exist" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/reserved_fields": { + "get": { + "operationId": "GET_contactdb-reserved_fields", + "summary": "Retrieve reserved fields", + "tags": [ + "Contacts API - Custom Fields" + ], + "description": "**This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "reserved_fields": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "type": { + "type": "string" + } + } + } + } + } + }, + "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": "lists", + "type": "set" + }, + { + "name": "campaigns", + "type": "set" + }, + { + "name": "my_custom_field", + "type": "text" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/segments": { + "post": { + "operationId": "POST_contactdb-segments", + "summary": "Create a Segment", + "tags": [ + "Contacts API - Segments" + ], + "description": "

\n Create a segment using search conditions.\n Body contains a JSON object with conditions, a list of conditions as described below, a unique name, and an optional list_id, which is a valid list ID for a list to limit the search on.\n

\n\n

\n Valid operators for create and update depend on the type of the field for which you are searching.\n

\n\n
    \n
  • Dates:\n
      \n
    • \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n
        \n
      • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
        • \n
      \n
      • \n
    • \"empty\", \"not_empty\"
      • \n
    • \"is within\"\n \n
      • \n
    \n
    • \n
  • Text: \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value), \"empty\", \"not_empty\"
    • \n
  • Numbers: \"eq\", \"lt\", \"gt\", \"empty\", \"not_empty\"
    • \n
  • Email Clicks and Opens: \"eq\" (opened), \"ne\" (not opened)
    • \n
\n\n

\n Field values must all be a string.\n

\n\n

\n Conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either clicks.campaign_identifier or opens.campaign_identifier.\n The condition value should be a string containing the id of a completed campaign.\n

\n\n

\n The conditions list may contain multiple conditions, joined by an \"and\" or \"or\" in the \"and_or\" field.\n The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n

", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/contactdb_segments", + "example": { + "name": "Last Name Miller", + "list_id": 4, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" + }, + { + "field": "last_clicked", + "value": "01/02/2015", + "operator": "gt", + "and_or": "and" + }, + { + "field": "clicks.campaign_identifier", + "value": "513", + "operator": "eq", + "and_or": "or" + } + ] + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_contactdb-segments", + "summary": "Retrieve all segments", + "tags": [ + "Contacts API - Segments" + ], + "description": "**This endpoint allows you to retrieve all of your segments.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/segments/{segment_id}": { + "parameters": [ + { + "name": "segment_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_contactdb-segments-segment_id", + "summary": "Retrieve a segment", + "tags": [ + "Contacts API - Segments" + ], + "description": "**This endpoint allows you to retrieve a single segment with the given ID.**", + "parameters": [ + { + "name": "segment_id", + "in": "query", + "description": "The ID of the segment you want to request.", + "required": true, + "type": "integer" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "if segment_id is not valid" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "segment_id not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_contactdb-segments-segment_id", + "summary": "Update a segment", + "tags": [ + "Contacts API - Segments" + ], + "description": "**This endpoint allows you to update a segment.**", + "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" + ], + "example": { + "name": "The Millers", + "list_id": 5, + "conditions": [ + { + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" + } + ] + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_contactdb-segments-segment_id", + "summary": "Delete a segment", + "tags": [ + "Contacts API - Segments" + ], + "description": "**This endpoint allows you to delete a segment from your recipients database.**\n\nYou also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.", + "parameters": [ + { + "name": "delete_contacts", + "in": "query", + "description": "True to delete all contacts matching the segment in addition to deleting the segment", + "type": "boolean" + }, + { + "name": "body", + "in": "body", + "schema": { + "type": "null" + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "segment_id", + "message": "segment_id does not exist" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/contactdb/segments/{segment_id}/recipients": { + "parameters": [ + { + "name": "segment_id", + "in": "path", + "description": "The ID of the segment from which you want to retrieve recipients.", + "required": true, + "type": "integer" + } + ], + "get": { + "operationId": "GET_contactdb-segments-segment_id-recipients", + "summary": "Retrieve recipients on a segment", + "tags": [ + "Contacts API - Segments" + ], + "description": "**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**", + "parameters": [ + { + "name": "page", + "in": "query", + "type": "integer" + }, + { + "name": "page_size", + "in": "query", + "type": "integer" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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\"", + "schema": { + "type": "object" + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "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\"", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/categories": { + "get": { + "operationId": "GET_categories", + "summary": "Retrieve all categories", + "tags": [ + "Categories" + ], + "description": "**This endpoint allows you to retrieve a list of all of your categories.**\n\nCategories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories.", + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "The number of categories to display per page.", + "type": "integer", + "default": 50 + }, + { + "name": "category", + "in": "query", + "description": "Allows you to perform a prefix search on this particular category.", + "type": "string" + }, + { + "name": "offset", + "in": "query", + "description": "The point in the list that you would like to begin displaying results.", + "type": "integer", + "default": 0 + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "category": { + "type": "string", + "description": "A category used to group emails by broad topic." + } + }, + "required": [ + "category" + ] + } + }, + "examples": { + "application/json": [ + { + "category": "category 1" + }, + { + "category": "category 2" + } + ] + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "description": "The error returned.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string", + "description": "A message explaining why your categories could not be retrieved." + } + }, + "required": [ + "field", + "message" + ] + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "sort_by", + "message": "invalid sort value" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/categories/stats/sums": { + "get": { + "operationId": "GET_categories-stats-sums", + "summary": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", + "tags": [ + "Categories" + ], + "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.\n\n> Category statistics are available for the previous thirteen months only.", + "parameters": [ + { + "name": "sort_by_metric", + "in": "query", + "description": "The metric that you want to sort by. Must be a single metric.", + "required": false, + "type": "string", + "default": "delivered" + }, + { + "name": "sort_by_direction", + "in": "query", + "description": "The direction you want to sort.", + "required": false, + "type": "string", + "default": "desc", + "enum": [ + "desc", + "asc" + ] + }, + { + "name": "start_date", + "in": "query", + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "required": true, + "type": "string" + }, + { + "name": "end_date", + "in": "query", + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "required": false, + "type": "string" + }, + { + "name": "limit", + "in": "query", + "description": "Limits the number of results returned.", + "required": false, + "type": "integer", + "default": 5 + }, + { + "name": "offset", + "in": "query", + "description": "The point in the list to begin retrieving results.", + "required": false, + "type": "integer", + "default": 0 + }, + { + "name": "aggregated_by", + "in": "query", + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "required": false, + "type": "string", + "enum": [ + "day", + "week", + "month" + ] + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/category_stats" + }, + "examples": { + "application/json": { + "date": "2015-01-01", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 20, + "deferred": 0, + "delivered": 20, + "invalid_emails": 0, + "opens": 20, + "processed": 0, + "requests": 20, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 20, + "unique_opens": 20, + "unsubscribe_drops": 0, + "unsubscribes": 20 + }, + "name": "cat1", + "type": "category" + }, + { + "metrics": { + "blocks": 1, + "bounce_drops": 0, + "bounces": 0, + "clicks": 19, + "deferred": 0, + "delivered": 19, + "invalid_emails": 0, + "opens": 19, + "processed": 0, + "requests": 20, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 19, + "unique_opens": 19, + "unsubscribe_drops": 0, + "unsubscribes": 19 + }, + "name": "cat2", + "type": "category" + }, + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 5, + "deferred": 0, + "delivered": 5, + "invalid_emails": 0, + "opens": 5, + "processed": 0, + "requests": 5, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 5, + "unique_opens": 5, + "unsubscribe_drops": 0, + "unsubscribes": 5 + }, + "name": "cat3", + "type": "category" + }, + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 6, + "deferred": 0, + "delivered": 5, + "invalid_emails": 0, + "opens": 6, + "processed": 0, + "requests": 5, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 5, + "unique_opens": 5, + "unsubscribe_drops": 0, + "unsubscribes": 6 + }, + "name": "cat4", + "type": "category" + }, + { + "metrics": { + "blocks": 10, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 10, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "cat5", + "type": "category" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/categories/stats": { + "get": { + "operationId": "GET_categories-stats", + "summary": "Retrieve Email Statistics for Categories", + "tags": [ + "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.\n\n> Category statistics are available for the previous thirteen months only.", + "parameters": [ + { + "name": "start_date", + "in": "query", + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD", + "required": true, + "type": "string" + }, + { + "name": "end_date", + "in": "query", + "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", + "required": false, + "type": "string" + }, + { + "name": "categories", + "in": "query", + "description": "The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.", + "required": true, + "type": "string" + }, + { + "name": "limit", + "in": "query", + "description": "The number of results to include.", + "required": false, + "type": "integer", + "default": 500, + "maximum": 500 + }, + { + "name": "offset", + "in": "query", + "description": "The number of results to skip.", + "required": false, + "type": "integer" + }, + { + "name": "aggregated_by", + "in": "query", + "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", + "required": false, + "type": "string", + "enum": [ + "day", + "week", + "month" + ] + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "array", + "items": { + "$ref": "#/definitions/category_stats" + } + }, + "examples": { + "application/json": [ + { + "date": "2015-10-01", + "stats": [ + { + "type": "category", + "name": "docs", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + }, + { + "type": "category", + "name": "mattscategory", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "type": "category", + "name": "docs", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + }, + { + "type": "category", + "name": "mattscategory", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/campaigns": { + "post": { + "operationId": "POST_campaigns", + "summary": "Create a Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to create a campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.\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.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/campaign_request", + "example": { + "title": "March Newsletter", + "subject": "New Products for Spring!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 + ], + "segment_ids": [ + 110 + ], + "categories": [ + "spring line" + ], + "suppression_group_id": 42, + "custom_unsubscribe_url": "", + "ip_pool": "marketing", + "html_content": "

Check out our spring line!

", + "plain_content": "Check out our spring line!" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "title", + "message": "title can't be blank" + }, + { + "field": "title", + "message": "title is too long (maximum is 100 characters)" + }, + { + "field": "categories", + "message": "categories exceeds 10 category limit" + }, + { + "field": "html_content", + "message": "html_content exceeds the 1MB limit" + }, + { + "field": "plain_content", + "message": "plain_content exceeds the 1MB limit" + }, + { + "field": "sender_id", + "message": "sender_id does not exist" + }, + { + "field": "sender_id", + "message": "sender_id is not a verified sender identity" + }, + { + "field": "list_ids", + "message": "list_ids do not all exist" + }, + { + "field": "segment_ids", + "message": "segment_ids do not all exist" + }, + { + "field": "ip_pool", + "message": "The ip pool you provided is invalid" + }, + { + "field": "suppression_group_id", + "message": "suppression_group_id does not exist" + }, + { + "field": "unsubscribes", + "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + }, + { + "field": null, + "message": "The JSON you have submitted cannot be parsed." + }, + { + "field": null, + "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_campaigns", + "summary": "Retrieve all Campaigns", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to retrieve a list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.", + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "The number of results you would like to receive at a time.", + "type": "integer", + "default": 10 + }, + { + "name": "offset", + "in": "query", + "description": "The index of the first campaign to return, where 0 is the first campaign.", + "type": "integer", + "default": 0 + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "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" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/campaigns/{campaign_id}": { + "parameters": [ + { + "name": "campaign_id", + "in": "path", + "description": "The id of the campaign you would like to retrieve.", + "required": true, + "type": "integer" + } + ], + "get": { + "operationId": "GET_campaigns-campaign_id", + "summary": "Retrieve a single campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to retrieve a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "categories": { + "type": "array", + "items": { + "type": "string" + } + }, + "custom_unsubscribe_url": { + "type": "string" + }, + "html_content": { + "type": "string" + }, + "id": { + "type": "integer" + }, + "ip_pool": { + "type": "string" + }, + "list_ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "plain_content": { + "type": "string" + }, + "segment_ids": { + "type": "array", + "items": { + "type": "integer" + } + }, + "sender_id": { + "type": "integer" + }, + "status": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "suppression_group_id": { + "type": "integer" + }, + "title": { + "type": "string" + } + } + }, + "examples": { + "application/json": { + "categories": [ + "spring line" + ], + "custom_unsubscribe_url": "", + "html_content": "

Check out our spring line!

", + "id": 986724, + "ip_pool": "marketing", + "list_ids": [ + 110 + ], + "plain_content": "Check out our spring line!", + "segment_ids": [ + 110 + ], + "sender_id": 124451, + "status": "Draft", + "subject": "New Products for Spring!", + "suppression_group_id": 42, + "title": "March Newsletter" + } + } + }, + "401": { + "description": "", + "schema": { + "type": "object" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"\": \"not found\"", + "schema": { + "type": "object" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_campaigns-campaign_id", + "summary": "Delete a Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to delete a specific campaign.**\n\nOur Marketing Campaigns API lets you create, manage, send, and schedule campaigns.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "401": { + "description": "", + "schema": { + "type": "object" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "authorization required" + } + ] + } + } + }, + "404": { + "description": "\"\": \"not found\"", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_campaigns-campaign_id", + "summary": "Update a Campaign", + "tags": [ + "Campaigns API" + ], + "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.", + "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" + ], + "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!" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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.\"", + "schema": { + "type": "object" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": "title", + "message": "title can't be blank" + }, + { + "field": "title", + "message": "title is too long (maximum is 100 characters)" + }, + { + "field": "categories", + "message": "categories exceeds 10 category limit" + }, + { + "field": "html_content", + "message": "html_content exceeds the 1MB limit" + }, + { + "field": "plain_content", + "message": "plain_content exceeds the 1MB limit" + }, + { + "field": "sender_id", + "message": "sender_id does not exist" + }, + { + "field": "sender_id", + "message": "sender_id is not a verified sender identity" + }, + { + "field": "list_ids", + "message": "list_ids do not all exist" + }, + { + "field": "segment_ids", + "message": "segment_ids do not all exist" + }, + { + "field": "ip_pool", + "message": "The ip pool you provided is invalid" + }, + { + "field": "suppression_group_id", + "message": "suppression_group_id does not exist" + }, + { + "field": "unsubscribes", + "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + }, + { + "field": null, + "message": "The JSON you have submitted cannot be parsed." + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + }, + "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" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/campaigns/{campaign_id}/schedules/now": { + "parameters": [ + { + "name": "campaign_id", + "in": "path", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_campaigns-campaign_id-schedules-now", + "summary": "Send a Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to immediately send a campaign at the time you make the API call.**\n\nNormally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/campaigns/{campaign_id}/schedules": { + "parameters": [ + { + "name": "campaign_id", + "in": "path", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_campaigns-campaign_id-schedules", + "summary": "Schedule a Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**\n\nIf you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won't be going through our servers at the same times as everyone else's mail.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "title": "Schedule a Campaign request", + "type": "object", + "properties": { + "send_at": { + "type": "integer", + "description": "The unix timestamp for the date and time you would like your campaign to be sent out." + } + }, + "required": [ + "send_at" + ], + "example": { + "send_at": 1489771528 + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_campaigns-campaign_id-schedules", + "summary": "Update a Scheduled Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "title": "Update a Scheduled Campaign request", + "type": "object", + "properties": { + "send_at": { + "type": "integer", + "format": "int64" + } + }, + "required": [ + "send_at" + ], + "example": { + "send_at": 1489451436 + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_campaigns-campaign_id-schedules", + "summary": "View Scheduled Time of a Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_campaigns-campaign_id-schedules", + "summary": "Unschedule a Scheduled Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/campaigns/{campaign_id}/schedules/test": { + "parameters": [ + { + "name": "campaign_id", + "in": "path", + "required": true, + "type": "integer" + } + ], + "post": { + "operationId": "POST_campaigns-campaign_id-schedules-test", + "summary": "Send a Test Campaign", + "tags": [ + "Campaigns API" + ], + "description": "**This endpoint allows you to send a test campaign.**\n\nTo send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]", + "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" + ], + "example": { + "to": "your.email@example.com" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "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_error_response_schema" + }, + "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_error_response_schema" + }, + "examples": { + "application/json": { + "errors": [ + { + "field": null, + "message": "not found" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/templates": { + "post": { + "operationId": "POST_templates", + "summary": "Create a transactional template.", + "tags": [ + "Transactional Templates" + ], + "description": "**This endpoint allows you to create a transactional template.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name for the new transactional template.", + "maxLength": 100 + }, + "generation": { + "type": "string", + "description": "Defines whether the template supports dynamic replacement.", + "enum": [ + "legacy", + "dynamic" + ], + "default": "legacy" + } + }, + "required": [ + "name" + ], + "example": { + "name": "example_name", + "generation": "dynamic" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template" + }, + "examples": { + "application/json": { + "id": "733ba07f-ead1-41fc-933a-3976baa23716", + "name": "example_name", + "generation": "legacy", + "versions": [] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_templates", + "summary": "Retrieve paged transactional templates.", + "tags": [ + "Transactional Templates" + ], + "description": "**This endpoint allows you to retrieve all transactional templates.**", + "parameters": [ + { + "name": "generations", + "in": "query", + "description": "Comma-delimited list specifying which generations of templates to return. Options are `legacy`, `dynamic` or `legacy,dynamic`.", + "required": false, + "type": "string", + "default": "legacy", + "enum": [ + "legacy", + "dynamic", + "legacy,dynamic" + ] + }, + { + "name": "page_size", + "in": "query", + "description": "The number of templates to be returned in each page of results", + "required": true, + "type": "number", + "minimum": 1, + "maximum": 200 + }, + { + "name": "page_token", + "in": "query", + "description": "A token corresponding to a specific page of results, as provided by metadata", + "required": false, + "type": "string" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "description": "", + "items": { + "$ref": "#/definitions/transactional-templates-template-lean" + } + }, + "_metadata": { + "$ref": "#/definitions/_metadata" + } + } + }, + "examples": { + "application/json": { + "result": [ + { + "id": "fae7c985-eb92-4b47-9987-28ec29dbc698", + "name": "example_name", + "generation": "legacy", + "updated_at ": "2020-11-12 12:00:09", + "versions": [] + } + ], + "_metadata": { + "self": "https://api.sendgrid.com/v3/templates", + "count": 1 + } + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "": { + "type": "string" + }, + "message": { + "type": "string" + }, + "error_id": { + "type": "string" + } + } + } + } + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/templates/{template_id}": { + "parameters": [ + { + "name": "template_id", + "in": "path", + "required": true, + "type": "string" + } + ], + "post": { + "operationId": "POST_templates-template_id", + "summary": "Duplicate a transactional template.", + "tags": [ + "Transactional Templates" + ], + "description": "**This endpoint allows you to duplicate a transactional template.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name for the new transactional template.", + "maxLength": 100 + } + }, + "example": { + "name": "example_name" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template" + }, + "examples": { + "application/json": { + "id": "733ba07f-ead1-41fc-933a-3976baa2371", + "name": "example_name", + "generation": "dynamic", + "updated_at ": "2019-03-13T11:52:41.009Z", + "versions": [] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "get": { + "operationId": "GET_templates-template_id", + "summary": "Retrieve a single transactional template.", + "tags": [ + "Transactional Templates" + ], + "description": "**This endpoint allows you to retrieve a single transactional template.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template" + }, + "examples": { + "application/json": { + "id": "40da60e6-66f3-4223-9406-ba58b7f55a62", + "name": "Duis in dolor", + "generation": "legacy", + "updated_at ": "2020-12-12 58:26:65", + "versions": [] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_templates-template_id", + "summary": "Edit a transactional template.", + "tags": [ + "Transactional Templates" + ], + "description": "**This endpoint allows you to edit the name of a transactional template.**\n\nTo edit the template itself, [create a new transactional template version](https://sendgrid.api-docs.io/v3.0/transactional-templates-versions/create-a-new-transactional-template-version).", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the transactional template.", + "maxLength": 100 + } + }, + "example": { + "name": "new_example_name" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template" + }, + "examples": { + "application/json": { + "id": "733ba07f-ead1-41fc-933a-3976baa23716", + "name": "new_example_name", + "versions": [] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_templates-template_id", + "summary": "Delete a template.", + "tags": [ + "Transactional Templates" + ], + "description": "**This endpoint allows you to delete a transactional template.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/templates/{template_id}/versions": { + "parameters": [ + { + "name": "template_id", + "in": "path", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "post": { + "operationId": "POST_templates-template_id-versions", + "summary": "Create a new transactional template version.", + "tags": [ + "Transactional Templates Versions" + ], + "description": "**This endpoint allows you to create a new version of a template.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/transactional_template_version_create", + "example": { + "active": 1, + "name": "example_version_name", + "html_content": "", + "plain_content": "Plain text content", + "generate_plain_content": false, + "subject": "", + "editor": "design" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template_version_output" + }, + "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%>", + "generate_plain_content": true, + "subject": "<%subject%>", + "updated_at": "2019-03-13 18:56:33", + "editor": "code" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/templates/{template_id}/versions/{version_id}/activate": { + "parameters": [ + { + "name": "template_id", + "in": "path", + "description": "The ID of the original template", + "required": true, + "type": "string", + "format": "uuid" + }, + { + "name": "version_id", + "in": "path", + "description": "The ID of the template version", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "post": { + "operationId": "POST_templates-template_id-versions-version_id-activate", + "summary": "Activate a transactional template version.", + "tags": [ + "Transactional Templates Versions" + ], + "description": "**This endpoint allows you to activate a version of one of your templates.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template_version_output" + }, + "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%>", + "generate_plain_content": true, + "subject": "<%subject%>", + "updated_at": "2019-03-13 18:56:33", + "editor": "code" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/templates/{template_id}/versions/{version_id}": { + "parameters": [ + { + "name": "template_id", + "in": "path", + "description": " The ID of the original template", + "required": true, + "type": "string", + "format": "uuid" + }, + { + "name": "version_id", + "in": "path", + "description": "The ID of the template version", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "get": { + "operationId": "GET_templates-template_id-versions-version_id", + "summary": "Retrieve a specific transactional template version.", + "tags": [ + "Transactional Templates Versions" + ], + "description": "**This endpoint allows you to retrieve a specific version of a template.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template_version_output" + }, + "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%>", + "generate_plain_content": true, + "subject": "<%subject%>", + "updated_at": "2019-03-13 18:56:33", + "editor": "code" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_templates-template_id-versions-version_id", + "summary": "Edit a transactional template version.", + "tags": [ + "Transactional Templates Versions" + ], + "description": "**This endpoint allows you to edit the content of your template version.**", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/transactional_template_version_create", + "example": { + "active": 1, + "name": "updated_example_name", + "html_content": "<%body%>", + "plain_content": "<%body%>", + "subject": "<%subject%>" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/transactional_template_version_output" + }, + "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%>", + "generate_plain_content": true, + "subject": "<%subject%>", + "updated_at": "2019-03-13 18:56:33", + "editor": "code" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_templates-template_id-versions-version_id", + "summary": "Delete a transactional template version.", + "tags": [ + "Transactional Templates Versions" + ], + "description": "**This endpoint allows you to delete a transactional template version.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/webhooks/event/settings": { + "get": { + "operationId": "GET_user-webhooks-event-settings", + "summary": "Retrieve Event Webhook settings", + "tags": [ + "Webhooks" + ], + "description": "**This endpoint allows you to retrieve your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/event-webhook-response" + }, + "examples": { + "application/json": { + "enabled": false, + "url": "incididunt reprehenderit", + "group_resubscribe": false, + "delivered": false, + "group_unsubscribe": false, + "spam_report": false, + "bounce": false, + "deferred": false, + "unsubscribe": true, + "processed": false, + "open": true, + "click": true, + "dropped": true, + "oauth_client_id": "est fugiat", + "oauth_token_url": "Duis in laborum sunt" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_user-webhooks-event-settings", + "summary": "Update Event Notification Settings", + "tags": [ + "Webhooks" + ], + "description": "**This endpoint allows you to update your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/event-webhook-update-oauth-request", + "example": { + "enabled": false, + "url": "id aliqua", + "group_resubscribe": true, + "delivered": false, + "group_unsubscribe": true, + "spam_report": true, + "bounce": false, + "deferred": false, + "unsubscribe": true, + "processed": false, + "open": false, + "click": false, + "dropped": false, + "oauth_client_id": "reprehenderit in null", + "oauth_client_secret": "ea in nostrud", + "oauth_token_url": "cupidatat ad Ut" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/event-webhook-response" + }, + "examples": { + "application/json": { + "enabled": true, + "url": "mollit laborum", + "group_resubscribe": false, + "delivered": true, + "group_unsubscribe": true, + "spam_report": true, + "bounce": true, + "deferred": true, + "unsubscribe": true, + "processed": true, + "open": true, + "click": false, + "dropped": true, + "oauth_client_id": "anim sunt", + "oauth_token_url": "ex" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/webhooks/parse/settings": { + "get": { + "operationId": "GET_user-webhooks-parse-settings", + "summary": "Retrieve all parse settings", + "tags": [ + "Webhooks" + ], + "description": "**This endpoint allows you to retrieve all of your current inbound parse settings.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "description": "The list of your current inbound parse settings.", + "items": { + "$ref": "#/definitions/parse-setting" + } + } + } + }, + "examples": { + "application/json": { + "result": [ + { + "url": "http://mydomain.com/parse", + "hostname": "mail.mydomain.com", + "spam_check": true, + "send_raw": true + } + ] + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "post": { + "operationId": "POST_user-webhooks-parse-settings", + "summary": "Create a parse setting", + "tags": [ + "Settings - Inbound Parse" + ], + "description": "**This endpoint allows you to create a new inbound parse setting.**\n\nCreating an Inbound Parse setting requires two pieces of information: a `url` and a `hostname`.\n\nThe `hostname` must correspond to a domain authenticated by Twilio SendGrid on your account. If you need to complete domain authentication, you can use the [Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth) or the #endpoint:aXpkWYramCg4ZNEGT endpoint. See \"[How to Set Up Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/)\" for instructions.\n\nAny email received by the `hostname` will be parsed when you complete this setup. You must also add a Twilio SendGrid MX record to this domain's DNS records. See \"[Setting up the Inbound Parse Webhook](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/)\" for full instructions.\n\nThe `url` represents a location where the parsed message data will be delivered. Twilio SendGrid will make an HTTP POST request to this `url` with the message data. The `url` must be publicly reachable, and your application must return a `200` status code to signal that the message data has been received.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/parse-setting", + "example": { + "hostname": "myhostname.com", + "url": "http://email.myhosthame.com", + "spam_check": true, + "send_raw": false + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "201": { + "description": "", + "schema": { + "$ref": "#/definitions/parse-setting" + }, + "examples": { + "application/json": { + "url": "http://email.myhostname.com", + "hostname": "myhostname.com", + "spam_check": false, + "send_raw": true + } + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/webhooks/parse/stats": { + "get": { + "operationId": "GET_user-webhooks-parse-stats", + "summary": "Retrieves Inbound Parse Webhook statistics.", + "tags": [ + "Webhooks" + ], + "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 30MB 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).", + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "The number of statistics to return on each page.", + "required": false, + "type": "string" + }, + { + "name": "offset", + "in": "query", + "description": "The number of statistics to skip.", + "required": false, + "type": "string" + }, + { + "name": "aggregated_by", + "in": "query", + "description": "How you would like the statistics to by grouped. ", + "required": false, + "type": "string", + "enum": [ + "day", + "week", + "month" + ] + }, + { + "name": "start_date", + "in": "query", + "description": "The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", + "required": true, + "type": "string" + }, + { + "name": "end_date", + "in": "query", + "description": "The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", + "required": false, + "type": "string", + "default": "The day the request is made." + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date that the stats were collected." + }, + "stats": { + "type": "array", + "description": "The Parse Webhook usage statistics.", + "items": { + "type": "object", + "properties": { + "metrics": { + "type": "object", + "properties": { + "received": { + "type": "number", + "description": "The number of emails received and parsed by the Parse Webhook." + } + }, + "required": [ + "received" + ] + } + } + } + } + }, + "required": [ + "date", + "stats" + ] + } + }, + "examples": { + "application/json": [ + { + "date": "2015-10-11", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-12", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-13", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-14", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-15", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-16", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-17", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-18", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-19", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-20", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-21", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-22", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-23", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-24", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-25", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-26", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-27", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-28", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-29", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-30", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-10-31", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-01", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-02", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-03", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-04", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-05", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-06", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-07", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-08", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-09", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + }, + { + "date": "2015-11-10", + "stats": [ + { + "metrics": { + "received": 0 + } + } + ] + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/webhooks/event/settings/signed": { + "get": { + "operationId": "GET_user-webhooks-event-settings-signed", + "summary": "Retrieve Signed Webhook Public Key", + "tags": [ + "Webhooks" + ], + "description": "**This endpoint allows you to retrieve your signed webhook's public key.**\n\nOnce you have enabled signing of the Event Webhook, you will need the public key provided to verify the signatures on requests coming from Twilio SendGrid. You can retrieve the public key from this endpoint at any time.\n\nFor more information about cryptographically signing the Event Webhook, see [Getting Started with the Event Webhook Security Features](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features).", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "public_key": { + "type": "string", + "description": "The public key you can use to verify the Twilio SendGrid signature." + } + }, + "required": [ + "public_key" + ] + }, + "examples": { + "application/json": { + "public_key": "anim quis in sint" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_user-webhooks-event-settings-signed", + "summary": "Enable/Disable Signed Webhook", + "tags": [ + "Webhooks" + ], + "description": "**This endpoint allows you to enable or disable signing of the Event Webhook.**\n\nThis endpoint takes a single boolean request parameter, `enabled`. You may either enable or disable signing of the Event Webhook using this endpoint. Once enabled, you can retrieve your public key using the `/webhooks/event/settings/signed` endpoint.\n\nFor more information about cryptographically signing the Event Webhook, see [Getting Started with the Event Webhook Security Features](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features).", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + }, + "required": [ + "enabled" + ], + "example": { + "enabled": true + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "public_key": { + "type": "string", + "description": "The public key you can use to verify the Twilio SendGrid signature." + } + }, + "required": [ + "public_key" + ] + }, + "examples": { + "application/json": { + "public_key": "voluptate id Excepteur proident" + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": [ + "string", + "null" + ] + }, + "message": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "mollit consequat dolore commodo", + "field": "anim Ut" + }, + { + "message": "qui" + }, + { + "message": "commodo dolor ipsum" + }, + { + "message": "minim fugiat amet", + "field": "quis consectetur eiusmod ullamco laboris" + } + ] + } + } + }, + "401": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": [ + "string", + "null" + ] + }, + "message": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "fugiat", + "field": "in proident" + }, + { + "message": "adipisicing veniam laboris sunt ullamco", + "field": "ut" + }, + { + "message": "id sunt consequat Duis irure" + }, + { + "message": "nisi", + "field": "in qui" + }, + { + "message": "tempor in eiusmod elit" + } + ] + } + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": [ + "string", + "null" + ] + }, + "message": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "Excepteur culpa esse ea ut" + }, + { + "message": "enim Excepteur dolore dolore" + }, + { + "message": "dolor occaecat" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/webhooks/event/test": { + "post": { + "operationId": "POST_user-webhooks-event-test", + "summary": "Test Event Notification Settings", + "tags": [ + "Webhooks" + ], + "description": "**This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.**\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.\n\n>**Tip**: Retry logic for this endpoint differs from other endpoints, which use a rolling 24-hour retry.\n\nIf your web server does not return a 2xx response type, we will retry a POST request until we receive a 2xx response or the maximum time of 10 minutes has expired.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "The URL where you would like the test notification to be sent." + }, + "oauth_client_id": { + "type": "string", + "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_client_secret and oauth_token_url fields." + }, + "oauth_client_secret": { + "type": "string", + "description": "This secret is needed only once to create an access token. SendGrid will store this secret, allowing you to update your Client ID and Token URL without passing the secret to SendGrid again. When passing data in this field, you must also include the oauth_client_id and oauth_token_url fields." + }, + "oauth_token_url": { + "type": "string", + "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id and oauth_client_secret fields." + } + }, + "example": { + "url": "mollit non ipsum magna", + "oauth_client_id": "nisi", + "oauth_client_secret": "veniam commodo ex sunt", + "oauth_token_url": "dolor Duis" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/messages": { + "get": { + "operationId": "GET-messages", + "summary": "Filter all messages", + "tags": [ + "Query", + "Messages" + ], + "description": "This is **BETA** functionality. You may not have access, and we reserve the right to change functionality without notice.\n\nFilter all messages to search your Email Activity. All queries need to be [URL encoded](https://meyerweb.com/eric/tools/dencoder/), and have this format:\n\n`query={query_type}=\"{query_content}\"`\n\nencoded, this would look like this:\n\n`query=type%3D%22query_content%22`\n\nfor example:\n\nFilter by a specific email - `query=to_email%3D%22example%40example.com%22`\n\nFilter by subject line - `query=subject%3d%22A%20Great%20Subject%22`\n\n**Full list of basic query types and examples:**\n\n\n| **Filter query** | **Unencoded Example** (put this one into the try it out query - it'll automatically encode it for you) | **Encoded Example** (use this one in your code) |\n|-----------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|\n| msg_id | msg_id=“filter0307p1las1-16816-5A023E36-1.0” | msg_id%3D%22filter0307p1las1-16816-5A023E36-1.0%22 |\n| from_email | from_email=“testing@sendgrid.net” | from_email%3D%22testing%40sendgrid.net%22 |\n| subject | subject=\"This is a subject test\" | subject%22This%20is%20a%20subject%20test%22 |\n| to_email | to_email=\"example@example.com\" | to_email%3D%22example%40example.com%22 |\n| status | | status%22processed%22 |\n| template_id | | |\n| asm_group_id | | |\n| api_key_id | | |\n| events | status=\"processed\" | status%3D%22processed%22 |\n| originating_ip | | |\n| categories | | |\n| unique_args | | |\n| outbound_ip | | |\n| last_event_time | last_event_time=“2017-11-07T23:13:58Z” | last_event_time%3D%E2%80%9C2017-11-07T23%3A13%3A58Z%E2%80%9D |\n| clicks | clicks=\"0\" | clicks%3D%220%22 |\n\nFor information about building compound queries, and for the full query language functionality, see the [query language reference](https://docs.google.com/a/sendgrid.com/document/d/1fWoKTFNfg5UUsB6t9KuIcSo9CetKF_T0bGfWJ_gdPCs/edit?usp=sharing).\n\nComing soon, example compound queries: limit + to email + date", + "parameters": [ + { + "name": "query", + "in": "query", + "description": "Use the query syntax to filter your email activity.", + "required": true, + "type": "string" + }, + { + "name": "limit", + "in": "query", + "description": "The number of messages returned. This parameter must be greater than 0 and less than or equal to 1000", + "required": false, + "type": "number", + "default": "10", + "minimum": 1, + "maximum": 1000 + }, + { + "name": "X-Query-Id", + "in": "header", + "required": false, + "type": "string" + }, + { + "name": "X-Cursor", + "in": "header", + "required": false, + "type": "string" + }, + { + "$ref": "#/parameters/trait:authorizationHeader:Authorization" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "messages": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/definitions/email-activity-response-common-fields" + }, + { + "type": "object", + "properties": { + "opens_count": { + "type": "integer", + "description": "The number of times the message was opened." + }, + "clicks_count": { + "type": "integer", + "description": "The number of times links in the message were clicked." + }, + "last_event_time": { + "type": "integer", + "description": "A timestamp of the last event received for the specific message." + } + } + } + ], + "title": "Abbv. Message", + "type": "object", + "properties": { + "from_email": { + "type": "string" + }, + "msg_id": { + "type": "string" + }, + "subject": { + "type": "string" + }, + "to_email": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "processed", + "delivered", + "not_delivered" + ] + }, + "opens_count": { + "type": "integer" + }, + "clicks_count": { + "type": "integer" + }, + "last_event_time": { + "type": "string", + "description": "iso 8601 format" + } + }, + "required": [ + "from_email", + "msg_id", + "subject", + "to_email", + "status", + "opens_count", + "clicks_count", + "last_event_time" + ], + "example": { + "from_email": "from@test.com", + "msg_id": "abc123", + "subject": "anim Duis sint veniam", + "to_email": "test@test.com", + "status": "processed", + "opens_count": 1, + "clicks_count": 2, + "last_event_time": "2017-10-13T18:56:21Z" + } + } + } + } + }, + "examples": { + "application/json": { + "messages": [ + { + "from_email": "from@test.com", + "msg_id": "abc123", + "subject": "something profound", + "to_email": "to@test.com", + "status": "processed", + "opens_count": 0, + "clicks_count": 0, + "last_event_time": 1495064728, + "last_timestamp": 1495064728 + }, + { + "from_email": "yeah@test.com", + "msg_id": "321befe", + "subject": "something profound", + "to_email": "nah@test.com", + "status": "delivered", + "opens_count": 500, + "clicks_count": 200, + "last_event_time": 1495064793, + "last_timestamp": 1495064793 + }, + { + "from_email": "sad@test.com", + "msg_id": "434512dfg", + "subject": "something sad", + "to_email": "reject@test.com", + "status": "not delivered", + "opens_count": 0, + "clicks_count": 0, + "last_event_time": 1495064993, + "last_timestamp": 1495064993 + } + ] + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + }, + "required": [ + "errors" + ] + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "invalid syntax: 'bad_field' is not a known field" + } + ] + } + } + }, + "429": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "too many requests" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/messages/{msg_id}": { + "parameters": [ + { + "name": "msg_id", + "in": "path", + "description": "The ID of the message you are requesting details for.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET-v3-messages-msg_id", + "summary": "Filter messages by message ID", + "tags": [ + "Query", + "Messages" + ], + "description": "This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice.\n\nGet all of the details about the specified message.", + "responses": { + "200": { + "description": "", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/email-activity-response-common-fields" + }, + { + "type": "object", + "example": { + "from_email": "jane_doe@example.com", + "msg_id": "in aliquip id aliqua", + "subject": "est incididunt adipisicing pariatur", + "to_email": "send@test.com", + "status": "not delivered", + "template_id": "123e4567-e89b-12d3-a456-426655440000", + "asm_group_id": 11376349, + "teammate": "", + "api_key_id": "sdfsdfsdf123", + "originating_ip": "2.3.4.5", + "events": [ + { + "event_name": "bounced", + "processed": 1492453589, + "server_response": "some error message" + } + ], + "categories": [ + "hi", + "bye" + ], + "unique_args": "{'key': 'value'}", + "outbound_ip": "1.2.3.4", + "outbound_ip_type": "dedicated" + }, + "properties": { + "template_id": { + "type": "string", + "description": "The ID associated with a Twilio SendGrid email template used to format the message." + }, + "asm_group_id": { + "type": "integer", + "minimum": 1, + "description": "The unsubscribe group associated with this email." + }, + "teammate": { + "type": "string", + "description": "Teammate's username", + "minLength": 0, + "maxLength": 64, + "pattern": "^$|^[A-Za-z0-9]+" + }, + "api_key_id": { + "type": "string", + "minLength": 3, + "maxLength": 50, + "pattern": "^[A-Za-z0-9]+", + "description": "The ID of the API Key used to authenticate the sending request for the message." + }, + "events": { + "type": "array", + "description": "List of events related to email message", + "items": { + "title": "Event", + "type": "object", + "example": { + "event_name": "bounced", + "processed": "2017-10-13T18:56:21Z", + "reason": "some reason", + "url": "http://3LX,MU}N=B8'd,K}>bEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*O0OiStFG.ZoRi2=j%fUVa]&re6k{hKqD-8vWE12Fb5JC6z>S@@'cWS~w5KtuIwv$8/JDD94CXx1n5yjC_I2lQ66zDj4MXe/4bqlcqqQ7evnQWTYx5roaEYMapyuzb/USpsyalh/HcYc9PmQfF8ND_C7bXnwFQ_fb_BHMXbIV8JN28/NjZdawDJ6kSWxLykSVTHzcISGPBRfs_rt3Uc65Vzj6LDSSMN8WRs70m0tAWs/fkDvjvm_7ZeV08YZeB9j9mS9BcE089Fn5UzDlTJW9vqDF5uipjlIVrNbM7oWE/MIJcjg2vJO20jA24WHrchrEXCvKcxriviSDl3tuyDxqdqRSekpm2aH6yW7_ylXj/nWsex4jm3rKvYw1uLq3Tp7qb9edhj8B_TnwLv1yjHSkgbA5jKI4BTqxugmwVTnFf2OFCFp/ZILLkoKgfwOyIK4reUIkhCjuhkwp/cqGaFAkeCFQXPB6DLYesLZ2M3KPuBsBrs3pr3HRbTtwaOzdKtGc8e0C0VTjrJ3GwljStMPrSuQWh6/vigHRasZ4P9kFv5DPVbHWZzPvtwUw0AMByt44YH678WpbAXXy4I/IVOHmErZTbw1mJ/3vd4uI5rr2zEO_YA9qJZLJT/wmBimbOyaMtmTNYr_FhgfkKMN3_1la7RCK8CIP3p26mbuHbdJV1j/5sTIKibInM5l2BoWdEi49bPqzagsfjKpGVbg0YQ8mjrLhI92/qy0eVYi34kBGVuLzxK2FLC8vwYUrbupjUYE23Mc_6nmHYRK1HF1QmZDZG1hw96I3MPbTZqeJOWGch230qDNxOgnHRNNM52k/3c7FeuRr88RwZGpif/4FaSAbdqkUNvJ9J9qX2tJS9x5vZlgD8k4YHIXDztrnwg2VPquj/uo_2MjbWybIF/NGJM2RFAsKV1S5iOejuTV4p12KlH1p0Dt5EpxCSIl0XoWuvyLYar77f_hzqNdWAyL0FDxGfj4ma4jwqdTTLNyeZEtguYoCHTFfY/HgJkpHx/yO23G7gLhKPvD459ceffHidFh7LipTxNF0GFXhIAPrWfhv7PkPmVofBoFFlo6/rMcHQ82d5VS8i1CCyLtfuT5WH9GqrsOY7xo3lxi7BNL93/PLRdQT3SObRFRERw68V5ZFvIuEQqFOFZQ848rWPLXYDGY658dyjZALf/Ug4EROi_ehNtzPwecer_RGBHxeMnpxrPAFZEL6YXNKzm8hh3HY4Uc4fgkjge5fXsR4CeTSkS66/FOD00deDKmN7XcHEj1LGlAmd4XlV8vFpXg2VazX4OLW8z6vXn5vntNGYO6eBCEKUwupRz9nQSMeZ/Pbmjoopyt6TxQBUfPkHBdgCIhqA1zDV72ARqGlK_ao9KVjvgbB98YeiieIyogkuOa4y0E5iUEdBopzovVgtY88yLijh9ww/tl0R5rI2P2_OxguTbv_wrfEm8jRjISEIqSE9q29RB3n8PeD4hu24rcsaEuTMCqniiLN0a2OtZiKxHnbsNB660Aq3/tEo2SHZBkkIFYXBbDNE7gLfvFz9ZaC_E2oV2quyK1Id5SkNkJBVRRgROWBc_XEOXktc4vRUKxy1MQ526Xilyo8/uI67lHH1Vlr4V3GVmweT4A16KMqzmVzvRDRFLpkBv2iu3Okc1vIqkC/426aOqeUm6SXIx16d8BWVRcmqKqizxDEF3JkLFgX0ab73CZ4GdJ9YaakJO7y4adFGzzIVLcn08UZ/pwDQ9BAuwuMc2yMnKihdvmLKbnAa1ATk9jFXQ9QAEMBHZLbPNvtS3pkpk0s6fyh2ceHa9Myy3fL/oqvPmq_14KzLgPZHaOlyb3tUoQM52fv/I78TqTGyB4WYD_vkm8gYHZcCF0dFIXsiXUbAbwR90Ldk8lsgxSL6rBvjPSlQq7N66NPzUVRYr3zSISupG_66uS4rJszHwmxmmraT3/zfVKxHXFHgxUDRmnwIMfdFKm4sf/qnRRccOLExJYGcZy8u65jo4gHDvO6vnpsdf0YtVWqDBJXa95/Y/qL7EYS73_t6/2xnWra9TTO0OtQNXEQ1XXLSLt6vPw1FTlE2aYCitDgUo7DyxiwuGtvmMKUkYCo/lqXouo2TGXZFF80lrCu1vKdxBgOOerlrsKrOJawGEzL8XzXdxkOMUT8HOzHPNOvDwsxc47mvpVzXEbX5DRaioOlm2U4flTG/6bZfLqJqHNtrKwC5U5NNG6_yNOW5Jg_bLmzUosi86IXxn7i04vRXXn92JmdE70TcdujehT1n15wtiD8ld5A65IV2W1801/wr0XcDIGiUSmxFfCozUCtBTFwln0uJ0cquSDXhj7JQADhYDGyz8WhqcPE7CP9xN93EUBrWczINbA4IsfckY8CZh68/Tak5dEhw8i_3rz/8U39D/iML1G_A8TsnKQ9/_S8o89fFc7Wx/f1nXF8H6OLVbPpp5IZg7UTZ2K0bSe3iBpsmkkJpxY_6zEHTJE3LbIANwF9Ik5Tu0ZJpjck7I07xlHR8mDW9FXclSQC/qJUGL5qByf2SY2Wd24hqKGrahLfqApQuRI8_DtU/Y8kH6DDif5kD6as3sIe6VbKYnU9c1URq/npTlE72m107FXxW9zktdzbBJAxt4udMFzjt2LPcBpqrMKGkrg4BHqKXwhFTspCWyYCjxJ/eFb3fd3BB5kb9D0yl3oOjeWtbJBqsboyzdLisRBn2MCtXO2O8eo4Hkm/2uJDoRjRCyIi2GNRkH0B3EkN6Z3vG40C985bAtM8eqHABzP2QRcKCz4ICOw_Xz249bJk8qM0/m4EeIWnx2ISf9TBU6_0KZ5QJ0VPOCPXxV9jCeK5W5/RV5nd7GUUXG0btDqUAa3DzpaRHX3klMAqL73hK4AGD3ItikmxF8vnSaqtsgOCpEePERt9qcUOJJP2aR0scPAf_1TkGSrgr5VF/XLM2i7YhC_3J9fA2Qwa0dbTedY/xGayjimEkuWSWvh7P5FNOum_l7qJPnA31lQq6ixqR0NKhO328rWfijqKHF6WR/5O0MJ4WNuIXk6xBtTOA9mK7CGUgWjaF5mB72PVnDpN8G6ERO39GqO/fCO96/A1mwIPWedF6HklU8jaQ_M5EUzwCsBE3/7FW2hbcD3GCOFCiLvObjn59o6CKoYlmTop/PZw2CLzvARAr5KaLhjIuZRSKTGlmYjvSoSELuvWi/QHUV7SJ0kF_1O3b_3a88cm/z7qD3Rp6MmoQdGPSyu1lXTpoETypgOMywfsr4ycV2LQr5XaE3UrQP/RzobA4rI_I3ceCUaRASmil2rV1TUiyljhdCFt8zmi1o2NyTzSBRNGP0lXU5Qtm6dKKp7lGRC19P2oSSFrxt85vWRNo1mv8odcL/TF7/MN1Ev7gY20MqlRSBrlwg5LZ4_Az7QnBnpbU3LkTC/oVb743VFtXMW4cK/3lw6wfBJZe_8DobxT_6/gCXp6QOs/LuqmrQHMQvTS6jfbqVFnPfLjrQ01Mb_F4lr3md6m87wpc1CYd9hdzgUL/aqz68HMDCxjGauC00Rajq9wGVYcWJ3j6rIaHIPwclftjARXFDg0yH8v/L6qDgIgGwbB3eZfjOXHAMXRFNMMihseZxYkcFAzLtYr94q9XpQeK4bKi9h_rWAMwcEHnS8/MHHlySbgy8azGEA0u9xsY96MRi45Qe74kZ9xlsI1t4Yutx8/gsjIiu7vNsKEyeTwd88BMExjWNcJHOSHRff57pJBMEAtPdbMETYorvUkRyErsqprxX0W45n0RRQ85w/JCOsYaxZOAFfzO0AdLpMCguFwl01fkFOKYrQeXfNn8w0KF4XS0k/fPx02fU7fFjUoXcPH7_9xo755WL8DNIU2ne4b6DpiROe473yUfD8_zSNUI1tpxzVYNA7GvVSYt8UtqHn3/_QwuOc4VeAI6RiAG5O5bcAxzQl96Q35emNwtTT_CYqHORCmyPj6By2hT_SCLf8m_xFxxe3YzvnxDZGq3qf__pq7Tw181/GosBAJy3MotiIxcYDASbY9sV4T2V/KoGHyJ64spdkQbJOHJ216JMSKj8ii5m8gxqJ2ypL81p5hbjWtjbUgSc8M_KTLuc0Owf1R/3vr/dKbQ2pJ4XEfXhnZTBQY7ZrClnVCnd5cMe9ic/aNF0yyOSQVVOecUFkK9IYFVR8VHdVf4/Nfu3nOEskHki1_r3At1HLOMniS6qNTvhS0hfqIuBiQBsd5aB7OdfVpYy1HdIR72gMToBlpHPsE5GrVO0J9/gcyB2xcyZ3UpTom8G3V48LUkk6kcJ6l1SL5Fgzbst0z3pDA4dzBfswbC8dW57_MkswDANNd8atPrOBSU5m2z66dP/mIYQ8iq/DcmBexkARDI47VzYuw5gwy8Lvym2_B2gxBokU9_T/fHCPjlpqjTsY6SgBOz1nlDh_HcSWYAqnyrZxbEO2erVJ4WPKNzjM3KaPXGH/dZryna1E28wxCrMqLCs9aL9oVBlDMjUcEryAyRh7xwN0uWGopdpkd7Du6O9EPjAj37sHkUiVs7WL6JyexoDF_n67MICvQnJ9FK/FVrp1uMZnmr7ijkMW87moNRBkXbVc2EA_hHOHmpbVGqr6WgNtJ7bBk1LrAPT8sKtE75vbe_L9VYqBHJ/njk.WIIj-V23pwC7ZahcIL0XnDPupL7ltwEc779Ofhrk9dt_wIOFsA8XwnCjrYqH2ty.F0XdS\"*;@kDYgfL4dwE/5I@>k|u0D:wGz\"_8=}RJM!Ybbwd}eN=ZB*esF&(iQ%FW]_FSA:3Ze4O*6&tG-Fe**/j^a&S8zIa#6gxL2NmnNMSVGF-Bf3z08tt0ug_UfNshhs4HJh0l1o24gjAN-Uck1OvWkGQSXH0glB7CnOm0gI", + "bounce_type": "soft", + "mx_server": "laborum nisi", + "http_user_agent": "quis re" + } + ], + "originating_ip": "204.173.18.0", + "categories": [ + "dolor", + "pie" + ], + "unique_args": "eu", + "outbound_ip": "181.40.184.87", + "outbound_ip_type": "dedicated", + "id": "2mMUdxV2HRfAeDiBTYs2IP" + } + } + }, + "400": { + "description": "", + "schema": { + "errors": [ + { + "message": "invalid syntax: 'bad_field' is not a known field" + } + ] + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "not found", + "field": "message_id" + } + ] + } + } + }, + "429": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "too many requests" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "consumes": [ + "application/json" + ], + "parameters": [ + { + "$ref": "#/parameters/trait:authorizationHeader:Authorization" + } + ] + } + }, + "/messages/download": { + "post": { + "operationId": "POST_v3-messages-download", + "summary": "Request CSV", + "tags": [ + "CSV (UI only)", + "V3" + ], + "description": "This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice.\n\nThis request will kick off a backend process to generate a CSV file. Once generated, the worker will then send an email for the user download the file. The link will expire in 3 days.\n\nThe CSV fill contain the last 1 million messages. This endpoint will be rate limited to 1 request every 12 hours (rate limit may change).\n\nThis endpoint is similar to the GET Single Message endpoint - the only difference is that /download is added to indicate that this is a CSV download requests but the same query is used to determine what the CSV should contain.", + "parameters": [ + { + "name": "query", + "in": "query", + "description": "Uses a SQL like syntax to indicate which messages to include in the CSV", + "required": false, + "type": "string" + }, + { + "$ref": "#/parameters/trait:authorizationHeader:Authorization" + } + ], + "responses": { + "202": { + "description": "", + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "pending" + ] + }, + "message": { + "type": "string" + } + } + }, + "examples": { + "application/json": { + "status": "pending", + "message": "An email will be sent to jane_doe@example.com when the CSV is ready to download." + } + } + }, + "400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "some error" + } + ] + } + } + }, + "429": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "too many requests", + "field": "" + } + ] + } + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "internal server error" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/messages/download/{download_uuid}": { + "parameters": [ + { + "name": "download_uuid", + "in": "path", + "description": "UUID used to locate the download csv request entry in the DB.\n\nThis is the UUID provided in the email sent to the user when their csv file is ready to download", + "required": true, + "type": "string", + "format": "uuid" + } + ], + "get": { + "operationId": "GET_v3-messages-download-download_uuid", + "summary": "Download CSV", + "tags": [ + "CSV (UI only)", + "V3" + ], + "description": "**This endpoint will return a presigned URL that can be used to download the CSV that was requested from the #endpoint:LhbZ87Wq5k9AyFWD6 endpoint.**", + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "presigned_url": { + "type": "string", + "format": "uri", + "description": "A signed link that will allow you to download the CSV file requested by the Request a CSV endpoint." + }, + "csv": { + "type": "string", + "minLength": 5, + "pattern": "^((http[s]?|ftp):\\/)?\\/?([^:\\/\\s]+)((\\/\\w+)*\\/)([\\w\\-\\.]+[^#?\\s]+)(.*)?(#[\\w\\-]+)?$", + "description": "Returns the aws signed link to the csv file which mako UI should perform a get on to trigger the csv download for the user" + } + }, + "required": [ + "csv" + ] + }, + "examples": { + "application/json": { + "presigned_url": "https://example.com", + "csv": "https://s3-us-west-2.amazonaws.com/sendgrid-rts-development-queries/013c31af-7c9a-49e6-922c-d990f4aff151.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAI4NOW7APZHRFYGWQ%2F20170728%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20170728T223936Z&X-Amz-Signature=5c13ede58b211799ab1a556280bd316c404eac3aef1450c47906a077166c4ab4" + } + } + }, + "404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "download token is invalid or expired", + "field": "" + } + ] + } + } + }, + "500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "examples": { + "application/json": { + "errors": [ + { + "message": "internal server error" + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ], + "parameters": [ + { + "$ref": "#/parameters/trait:authorizationHeader:Authorization" + } + ] + } + }, + "/tracking_settings": { + "get": { + "operationId": "GET_tracking_settings", + "summary": "Retrieve Tracking Settings", + "tags": [ + "Settings - Tracking" + ], + "description": "**This endpoint allows you to retrieve a list of all tracking settings on your account.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "result": { + "type": "array", + "description": "The list of all tracking settings.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the event being tracked." + }, + "title": { + "type": "string", + "description": "The title of the tracking setting." + }, + "description": { + "type": "string", + "description": "A description about the event that is being tracked." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if this tracking setting is currently enabled." + } + } + } + } + } + }, + "examples": { + "application/json": { + "result": [ + { + "name": "open", + "title": "Open Tracking", + "description": "lorem ipsum... .", + "enabled": true + } + ] + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/tracking_settings/click": { + "get": { + "operationId": "GET_tracking_settings-click", + "summary": "Retrieve Click Track Settings", + "tags": [ + "Settings - Tracking" + ], + "description": "**This endpoint allows you to retrieve your current click tracking setting.**\n\nClick Tracking overrides all the links and URLs in your emails and points them to either SendGrid’s servers or the domain with which you branded your link. When a customer clicks a link, SendGrid tracks those [clicks](https://sendgrid.com/docs/glossary/clicks/).\n\nClick tracking helps you understand how users are engaging with your communications. SendGrid can track up to 1000 links per email", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/click-tracking" + }, + "examples": { + "application/json": { + "enable_text": false, + "enabled": true + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_tracking_settings-click", + "summary": "Update Click Tracking Settings", + "tags": [ + "Settings - Tracking" + ], + "description": "**This endpoint allows you to enable or disable your current click tracking setting.**\n\nClick Tracking overrides all the links and URLs in your emails and points them to either SendGrid’s servers or the domain with which you branded your link. When a customer clicks a link, SendGrid tracks those [clicks](https://sendgrid.com/docs/glossary/clicks/).\n\nClick tracking helps you understand how users are engaging with your communications. SendGrid can track up to 1000 links per email", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "The setting you want to use for click tracking." + } + }, + "example": { + "enabled": true + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/click-tracking" + }, + "examples": { + "application/json": { + "enable_text": false, + "enabled": true + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/tracking_settings/google_analytics": { + "get": { + "operationId": "GET_tracking_settings-google_analytics", + "summary": "Retrieve Google Analytics Settings", + "tags": [ + "Settings - Tracking" + ], + "description": "**This endpoint allows you to retrieve your current setting for Google Analytics.**\n\n\nGoogle Analytics helps you understand how users got to your site and what they're doing there. 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).\n\nWe default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/ui/analytics-and-reporting/google-analytics/).", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/google_analytics_settings" + }, + "examples": { + "application/json": { + "enabled": true, + "utm_campaign": "", + "utm_content": "lotsandlotsofcontent", + "utm_medium": "", + "utm_source": "", + "utm_term": "" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_tracking_settings-google_analytics", + "summary": "Update Google Analytics Settings", + "tags": [ + "Settings - Tracking" + ], + "description": "**This endpoint allows you to update your current setting for Google Analytics.**\n\nGoogle Analytics helps you understand how users got to your site and what they're doing there. 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).\n\nWe default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/ui/analytics-and-reporting/google-analytics/).", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/google_analytics_settings", + "example": { + "enabled": true, + "utm_source": "sendgrid.com", + "utm_medium": "email", + "utm_term": "", + "utm_content": "", + "utm_campaign": "website" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/google_analytics_settings" + }, + "examples": { + "application/json": { + "enabled": true, + "utm_campaign": "", + "utm_content": "lotsandlotsofcontent", + "utm_medium": "", + "utm_source": "", + "utm_term": "" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/tracking_settings/open": { + "get": { + "operationId": "GET_tracking_settings-open", + "summary": "Get Open Tracking Settings", + "tags": [ + "Settings - Tracking" + ], + "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.\n\nIf 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.\n\nThese events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if open tracking is enabled." + } + }, + "required": [ + "enabled" + ] + }, + "examples": { + "application/json": { + "enabled": true + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_tracking_settings-open", + "summary": "Update Open Tracking Settings", + "tags": [ + "Settings - Tracking" + ], + "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.\n\nIf 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.\n\nThese events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "The new status that you want to set for open tracking." + } + }, + "example": { + "enabled": true + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if open tracking is enabled." + } + }, + "required": [ + "enabled" + ] + }, + "examples": { + "application/json": { + "enabled": true + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/tracking_settings/subscription": { + "get": { + "operationId": "GET_tracking_settings-subscription", + "summary": "Retrieve Subscription Tracking Settings", + "tags": [ + "Settings - Tracking" + ], + "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.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/subscription_tracking_settings" + }, + "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": "" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "patch": { + "operationId": "PATCH_tracking_settings-subscription", + "summary": "Update Subscription Tracking Settings", + "tags": [ + "Settings - Tracking" + ], + "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.", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/subscription_tracking_settings", + "example": { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content": "html content", + "plain_content": "text content" + } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/subscription_tracking_settings" + }, + "examples": { + "application/json": { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content": "html content", + "plain_content": "text content" + } + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/stats": { + "get": { + "operationId": "GET_stats", + "summary": "Retrieve global email statistics", + "tags": [ + "Stats" + ], + "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.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" + } + ], + "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": { + "$ref": "#/definitions/stats-advanced-global-stats" + } + } + } + } + }, + "required": [ + "date", + "stats" + ] + } + }, + "examples": { + "application/json": [ + { + "date": "2015-11-03", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-04", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-05", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-06", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-07", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-08", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + }, + { + "date": "2015-11-09", + "stats": [ + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + } + } + ] + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/geo/stats": { + "get": { + "operationId": "GET_geo-stats", + "summary": "Retrieve email statistics by country and state/province.", + "tags": [ + "Stats" + ], + "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).", + "parameters": [ + { + "name": "country", + "in": "query", + "description": "The country you would like to see statistics for. Currently only supported for US and CA.", + "type": "string", + "enum": [ + "US", + "CA" + ] + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "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": { + "$ref": "#/definitions/advanced_stats_clicks_opens" + } + } + } + } + } + } + }, + "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 + } + } + ] + } ] } } - }, - "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": { - "operationId": "DELETE_asm-groups-group_id-suppressions-email", - "summary": "Delete a suppression from a suppression group", + "/devices/stats": { + "get": { + "operationId": "GET_devices-stats", + "summary": "Retrieve email statistics by device type.", "tags": [ - "Suppressions - Suppressions" + "Stats" ], - "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.", + "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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "null" - } - } - }, - "security": [ + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" + }, { - "Authorization": [] - } - ] - } - }, - "/asm/suppressions": { - "get": { - "operationId": "GET_asm-suppressions", - "summary": "Retrieve all suppressions", - "tags": [ - "Suppressions - Suppressions" - ], - "description": "**This endpoint allows you to retrieve a list of all suppressions.**\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", - "produces": [ - "application/json" - ], - "parameters": [ + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" + }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } ], "responses": { @@ -17258,50 +26717,437 @@ "items": { "type": "object", "properties": { - "email": { - "type": "string", - "description": "The email address that was suppressed." - }, - "group_id": { - "type": "integer", - "description": "The id of the suppression group that this email address belongs to." - }, - "group_name": { + "date": { "type": "string", - "description": "The name of the suppression group that this email address belongs to." + "description": "The date that the statistics were gathered." }, - "created_at": { - "type": "integer", - "description": "A UNIX timestamp indicating when the suppression was created." + "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": { + "$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 + } + } + ] }, - "required": [ - "email", - "group_id", - "group_name", - "created_at" - ] - } - }, - "examples": { - "application/json": [ { - "email": "test1@example.com", - "group_id": 1, - "group_name": "Weekly News", - "created_at": 1410986704 + "date": "2015-10-22", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] }, { - "email": "test1@example.com", - "group_id": 2, - "group_name": "Daily News", - "created_at": 1411493671 + "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 + } + } + ] }, { - "email": "test2@example.com", - "group_id": 2, - "group_name": "Daily News", - "created_at": 1411493671 + "date": "2015-11-10", + "stats": [ + { + "type": "device", + "name": "Webmail", + "metrics": { + "opens": 0, + "unique_opens": 0 + } + } + ] } ] } @@ -17314,104 +27160,92 @@ ] } }, - "/asm/suppressions/{email}": { - "parameters": [ - { - "name": "email", - "in": "path", - "description": "The email address that you want to search suppression groups for.", - "required": true, - "type": "string" - } - ], + "/clients/stats": { "get": { - "operationId": "GET_asm-suppressions-email", - "summary": "Retrieve all suppression groups for an email address", + "operationId": "GET_clients-stats", + "summary": "Retrieve email statistics by client type.", "tags": [ - "Suppressions - Suppressions" - ], - "description": "**This endpoint returns the list of all groups that the given email address has been unsubscribed from.**\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", - "produces": [ - "application/json" + "Stats" ], + "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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + }, + { + "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:start_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:end_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:aggregated_by" } ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "suppressions": { - "type": "array", - "description": "The array of suppression groups.", - "items": { - "type": "object", - "properties": { - "description": { - "type": "string", - "description": "The description of the suppression group." - }, - "id": { - "type": "integer", - "description": "The id of the suppression group." - }, - "is_default": { - "type": "boolean", - "description": "Indicates if the suppression group is set as the default." - }, - "name": { - "type": "string", - "description": "The name of the suppression group." - }, - "suppressed": { - "type": "boolean", - "description": "Indicates if the given email address is suppressed for this group." + "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": { + "$ref": "#/definitions/advanced_stats_opens" + } } - }, - "required": [ - "description", - "id", - "is_default", - "name", - "suppressed" - ] + } } } - }, - "required": [ - "suppressions" - ] + } }, "examples": { - "application/json": { - "suppressions": [ - { - "description": "Optional description.", - "id": 1, - "is_default": true, - "name": "Weekly News", - "suppressed": true - }, - { - "description": "Some daily news.", - "id": 2, - "is_default": true, - "name": "Daily News", - "suppressed": true - }, - { - "description": "An old group.", - "id": 2, - "is_default": false, - "name": "Old News", - "suppressed": false - } - ] - } + "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" + } + ] + } + ] } } }, @@ -17422,115 +27256,41 @@ ] } }, - "/asm/groups/{group_id}/suppressions/search": { + "/clients/{client_type}/stats": { "parameters": [ { - "name": "group_id", + "name": "client_type", "in": "path", - "description": "The ID of the suppression group that you would like to search.", + "description": "Specifies the type of client to retrieve stats for. Must be either \"phone\", \"tablet\", \"webmail\", or \"desktop\".", "required": true, - "type": "string" + "type": "string", + "enum": [ + "phone", + "tablet", + "webmail", + "desktop" + ] } ], - "post": { - "operationId": "POST_asm-groups-group_id-suppressions-search", - "summary": "Search for suppressions within a group", - "tags": [ - "Suppressions - Suppressions" - ], - "description": "**This endpoint allows you to search a suppression group for multiple suppressions.**\n\nWhen given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "description": "The list of email address that you want to search the suppression group for.", - "items": { - "type": "string" - } - } - }, - "required": [ - "recipient_emails" - ], - "example": { - "recipient_emails": [ - "exists1@example.com", - "exists2@example.com", - "doesnotexists@example.com" - ] - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "recipient_emails": { - "type": "array", - "description": "The email address from your search that do exist in the suppression group.", - "items": { - "type": "string" - } - } - }, - "required": [ - "recipient_emails" - ] - }, - "examples": { - "application/json": { - "recipient_emails": [ - "exists1@example.com", - "exists2@example.com" - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/groups": { "get": { - "operationId": "GET_asm-groups", - "summary": "Retrieve information about multiple suppression groups", + "operationId": "GET_clients-client_type-stats", + "summary": "Retrieve stats by a specific client type.", "tags": [ - "Suppressions - Unsubscribe Groups" - ], - "description": "**This endpoint allows you to retrieve information about multiple suppression groups.**\n\nThis endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.\n\nSuppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html).\n\nSuppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content.", - "produces": [ - "application/json" + "Stats" ], + "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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { - "name": "id", - "in": "query", - "description": "The ID of a suppression group that you want to retrieve information for.", - "type": "integer" + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:start_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:end_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:aggregated_by" } ], "responses": { @@ -17539,26 +27299,62 @@ "schema": { "type": "array", "items": { - "$ref": "#/definitions/suppression_group" + "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": { + "$ref": "#/definitions/advanced_stats_opens" + } + } + } + } + } } }, "examples": { "application/json": [ { - "id": 100, - "name": "Newsletters", - "description": "Our monthly newsletter.", - "last_email_sent_at": null, - "is_default": true, - "unsubscribes": 400 + "date": "2014-10-01", + "stats": [ + { + "metrics": { + "opens": 1, + "unique_opens": 1 + }, + "name": "Gmail", + "type": "client" + } + ] }, { - "id": 101, - "name": "Alerts", - "description": "Emails triggered by user-defined rules.", - "last_email_sent_at": null, - "is_default": false, - "unsubscribes": 1 + "date": "2014-10-02", + "stats": [ + { + "metrics": { + "opens": 0, + "unique_opens": 0 + }, + "name": "Gmail", + "type": "client" + } + ] } ] } @@ -17569,883 +27365,791 @@ "Authorization": [] } ] - }, - "post": { - "operationId": "POST_asm-groups", - "summary": "Create a new suppression group", + } + }, + "/mailbox_providers/stats": { + "get": { + "operationId": "GET_mailbox_providers-stats", + "summary": "Retrieve email statistics by mailbox provider.", "tags": [ - "Suppressions - Unsubscribe Groups" - ], - "description": "**This endpoint allows you to create a new suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Stats" ], + "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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name that you would like to use for your new suppression group.", - "maxLength": 30 - }, - "description": { - "type": "string", - "description": "A brief description of your new suppression group.", - "maxLength": 100 - }, - "is_default": { - "type": "boolean", - "description": "Indicates if you would like this to be your default suppression group." - } - }, - "required": [ - "name", - "description" - ], - "example": { - "name": "Product Suggestions", - "description": "Suggestions for products our users might like.", - "is_default": true - } - } + "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.", + "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } ], "responses": { - "201": { + "200": { "description": "", "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the suppression group." + "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": { + "$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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "name": { - "type": "string", - "description": "The name of the suppression group." + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "description": { - "type": "string", - "description": "A brief description of the suppression group." + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "is_default": { - "type": "boolean", - "description": "Indicates if this is the default suppression group." - } - }, - "required": [ - "id", - "name", - "description", - "is_default" - ] - }, - "examples": { - "application/json": { - "id": 103, - "name": "Product Suggestions", - "description": "Suggestions for products our users might like.", - "is_default": false - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/asm/groups/{group_id}": { - "parameters": [ - { - "name": "group_id", - "in": "path", - "description": "The ID of the suppression group you would like to retrieve.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_asm-groups-group_id", - "summary": "Get information on a single suppression group.", - "tags": [ - "Suppressions - Unsubscribe Groups" - ], - "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.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "description": { - "type": "string", - "description": "The description of the suppression group." + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "id": { - "type": "integer", - "description": "The ID of the suppression group." + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "is_default": { - "type": "boolean", - "description": "Indicates if this is the default suppression group." + { + "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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 1 + } + } + ] }, - "last_email_sent_at": { - "type": "null", - "description": "A unix timestamp indicating the last time this group was assigned to an email." + { + "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 + } + } + ] }, - "name": { - "type": "string", - "description": "The name of the suppression group." + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "unsubscribes": { - "type": "integer", - "description": "The number of unsubscribes, or suppressions, in this group." - } - } - }, - "examples": { - "application/json": { - "description": "Our monthly newsletter.", - "id": 100, - "is_default": true, - "last_email_sent_at": null, - "name": "Newsletters", - "unsubscribes": 400 - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "operationId": "PATCH_asm-groups-group_id", - "summary": "Update a suppression group.", - "tags": [ - "Suppressions - Unsubscribe Groups" - ], - "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.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the suppression group." + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "name": { - "type": "string", - "description": "The name of the suppression group. Each group created by a user must have a unique name.", - "maxLength": 30 + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "description": { - "type": "string", - "description": "The description of the suppression group.", - "maxLength": 100 + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 2 + } + } + ] }, - "is_default": { - "type": "boolean", - "description": "Indicates if the suppression group is set as the default group." - } - }, - "required": [ - "name" - ], - "example": { - "id": 103, - "name": "Item Suggestions", - "description": "Suggestions for items our users might like." - } - } - }, - { - "$ref": "#/parameters/trait:authorizationHeader:Authorization" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/suppression_group" - }, - "examples": { - "application/json": { - "id": 103, - "name": "Item Suggestions", - "description": "Suggestions for items our users might like." - } - } - } - } - }, - "delete": { - "operationId": "DELETE_asm-groups-group_id", - "summary": "Delete a suppression group.", - "tags": [ - "Suppressions - Unsubscribe Groups" - ], - "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.", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/scopes/requests": { - "get": { - "operationId": "GET_v3-scopes-requests", - "summary": "Retrieve access requests", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to retrieve a list of all recent access requests.\n\n**Note:** The Response Header's 'link' parameter will include pagination info. For example:\n\nlink: ```; rel=\"first\"; title=\"1\", ; rel=\"last\"; title=\"2\", ; rel=\"prev\"; title=\"1\"```", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Optional field to limit the number of results returned.", - "type": "integer", - "default": 50 - }, - { - "name": "offset", - "in": "query", - "description": "Optional beginning point in the list to retrieve from.", - "type": "integer", - "default": 0 - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "Request ID" - }, - "scope_group_name": { - "type": "string", - "description": "Name of group of scopes associated to page teammate is requesting access to" - }, - "username": { - "type": "string", - "description": "Teammate's username" - }, - "email": { - "type": "string", - "description": "Teammate's email" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - } - } - } - }, - "examples": { - "application/json": [ { - "id": 1, - "scope_group_name": "Mail Settings", - "username": "teammate1", - "email": "teammate1@example.com", - "first_name": "Teammate", - "last_name": "One" + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, { - "id": 2, - "scope_group_name": "Stats", - "username": "teammate2", - "email": "teammate2@example.com", - "first_name": "Teammate", - "last_name": "Two" - } - ] - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/scopes/requests/{request_id}": { - "parameters": [ - { - "name": "request_id", - "in": "path", - "description": "The ID of the request that you want to deny.", - "required": true, - "type": "string" - } - ], - "delete": { - "operationId": "DELETE_v3-scopes-requests-request_id", - "summary": "Deny access request", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to deny an attempt to access your account.\n\n**Note:** Only teammate admins may delete a teammate's access request.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "responses": { - "204": { - "description": "" - }, - "401": { - "description": "" - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 } } - } - } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Cannot find request", - "field": "request_id" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/scopes/requests/{request_id}/approve": { - "parameters": [ - { - "name": "request_id", - "in": "path", - "description": "The ID of the request that you want to approve.", - "required": true, - "type": "string" - } - ], - "patch": { - "operationId": "PATCH_v3-scopes-requests-approve-id", - "summary": "Approve access request", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to approve an access attempt.\n\n**Note:** Only teammate admins may approve another teammate’s access request.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "scope_group_name": { - "type": "string", - "description": "name of feature teammate will be given access to" - } - } - }, - "examples": { - "application/json": { - "scope_group_name": "Stats" - } - } - }, - "401": { - "description": "", - "schema": { - "type": "object" - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" + ] + }, + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 } } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/teammates/pending/{token}/resend": { - "parameters": [ - { - "name": "token", - "in": "path", - "description": "The token for the invite that you want to resend.", - "required": true, - "type": "string" - } - ], - "post": { - "operationId": "POST_v3-teammates-pending-token-resend", - "summary": "Resend teammate invite", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to resend a teammate invite.\n\n**Note:** Teammate invitations will expire after 7 days. Resending an invite will reset the expiration date.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "token": { - "type": "string", - "description": "ID to identify invite" - }, - "email": { - "type": "string", - "description": "Teammate's email address" + ] }, - "scopes": { - "type": "array", - "description": "Initial set of permissions to give to teammate if they accept the invite", - "items": { - "type": "string" - } + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate should have admin privileges" - } - } - }, - "examples": { - "application/json": { - "pending_id": "abc123abc", - "email": "teammate1@example.com", - "scopes": [ - "user.profile.read", - "user.profile.update" - ], - "is_admin": false - } - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 } } - } - } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "invalid pending key", - "field": "pending_key" - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/teammates/pending": { - "get": { - "operationId": "GET_v3-teammates-pending", - "summary": "Retrieve all pending teammates", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to retrieve a list of all pending teammate invitations.\n\n**Note:** Each teammate invitation is valid for 7 days. Users may resend the invite to refresh the expiration date.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "Email address teammate invite will be sent to" - }, - "scopes": { - "type": "array", - "description": "List of permissions to give teammate if they accept", - "items": { - "type": "string" - } - }, - "is_admin": { - "type": "boolean", - "description": "Set to true to indicate teammate should have the same set of permissions as parent user" - }, - "token": { - "type": "string", - "description": "Invitation token used to identify user" - }, - "expiration_date": { - "type": "integer", - "description": "timestamp indicates when invite will expire. Expiration is 7 days after invite creation" + ] + }, + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 } } - } - } - } - }, - "examples": { - "application/json": { - "result": [ - { - "email": "user1@example.com", - "scopes": [ - "user.profile.read", - "user.profile.edit" - ], - "is_admin": false, - "pending_id": "abcd123abc", - "expiration_date": 1456424263 - }, - { - "email": "user2@example.com", - "scopes": [], - "is_admin": true, - "pending_id": "bcde234bcd", - "expiration_date": 1456424263 - } - ] - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/teammates/pending/{token}": { - "parameters": [ - { - "name": "token", - "in": "path", - "description": "The token for the invite you want to delete.", - "required": true, - "type": "string" - } - ], - "delete": { - "operationId": "DELETE_v3-teammates-pending-token", - "summary": "Delete pending teammate", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to delete a pending teammate invite.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "responses": { - "204": { - "description": "" - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 } } - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/teammates": { - "post": { - "operationId": "POST_v3-teammates", - "summary": "Invite teammate", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to send a teammate invitation via email with a predefined set of scopes, or permissions.\n\n**Note:** A teammate invite will expire after 7 days, but you may resend the invite at any time to reset the expiration date.\n\nEssentials, [Legacy Lite](https://sendgrid.com/docs/Classroom/Basics/Billing/legacy_lite_plan.html), and Free Trial users may create up to one teammate per account. There are no limits for how many teammates a Pro or higher account may create.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "New teammate's email", - "minLength": 5, - "maxLength": 255, - "pattern": "^.*@.*\\..*" + ] }, - "scopes": { - "type": "array", - "description": "Set to specify list of scopes that teammate should have. Should be empty if teammate is an admin.", - "items": { - "type": "string" - } + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "is_admin": { - "type": "boolean", - "default": false, - "description": "Set to true if teammate should be an admin user" - } - }, - "required": [ - "email", - "scopes", - "is_admin" - ], - "example": { - "email": "teammate1@example.com", - "scopes": [ - "user.profile.read", - "user.profile.update" - ], - "is_admin": false - } - } - } - ], - "responses": { - "201": { - "description": "", - "schema": { - "type": "object", - "properties": { - "token": { - "type": "string", - "description": "Token to identify invite" + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "email": { - "type": "string", - "description": "Teammate's email address" + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "scopes": { - "type": "array", - "description": "Initial set of permissions to give to teammate if they accept the invite", - "items": {} + { + "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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate should have admin privileges" - } - } - }, - "examples": { - "application/json": { - "email": "teammate1@example.com", - "scopes": [ - "user.profile.read", - "user.profile.update" - ], - "is_admin": false - } - } - }, - "400": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" + { + "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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 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, + "processed": 0, + "requests": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0 + } + } + ] } - } + ] } } }, @@ -18454,236 +28158,122 @@ "Authorization": [] } ] - }, + } + }, + "/browsers/stats": { "get": { - "operationId": "GET_v3-teammates", - "summary": "Retrieve all teammates", + "operationId": "GET_browsers-stats", + "summary": "Retrieve email statistics by browser.", "tags": [ - "Teammates" + "Stats" ], - "description": "This endpoint allows you to retrieve a list of all current teammates.\n\n**Note:** The Response Header will include pagination info. For example:\n\nlink: ```; rel=\"first\"; title=\"1\", ; rel=\"last\"; title=\"2\", ; rel=\"prev\"; title=\"1\"```", + "description": "**This endpoint allows you to retrieve your email statistics segmented by browser type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { - "name": "limit", + "name": "browsers", "in": "query", - "description": "Number of items to return", - "type": "integer", - "default": 500, - "minimum": 0, - "maximum": 500 + "description": "The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times.", + "type": "string" }, { - "name": "offset", - "in": "query", - "description": "Paging offset", - "type": "integer", - "default": 0, - "minimum": 0 - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Teammate's username" - }, - "email": { - "type": "string", - "description": "Teammate's email" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - }, - "user_type": { - "type": "string", - "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", - "enum": [ - "admin", - "owner", - "teammate" - ] - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate has admin privileges" - }, - "phone": { - "type": "string", - "description": "(optional) Teammate's phone number" - }, - "website": { - "type": "string", - "description": "(optional) Teammate's website" - }, - "address": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "address2": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "city": { - "type": "string", - "description": "(optional) Teammate's city" - }, - "state": { - "type": "string", - "description": "(optional) Teammate's state" - }, - "zip": { - "type": "string", - "description": "(optional) Teammate's zip" - }, - "country": { - "type": "string", - "description": "(optional) Teammate's country" - } - } - } - } - } - } - } - }, - "security": [ + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + }, { - "Authorization": [] + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" + }, + { + "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } - ] - } - }, - "/teammates/{username}": { - "parameters": [ - { - "name": "username", - "in": "path", - "description": "The username of the teammate that you want to retrieve.", - "required": true, - "type": "string" - } - ], - "get": { - "operationId": "GET_v3-teammates-username", - "summary": "Retrieve specific teammate", - "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to retrieve a specific teammate by username.", - "produces": [ - "application/json" ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Teammate's username" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - }, - "email": { - "type": "string", - "description": "Teammate's email" - }, - "scopes": { - "type": "array", - "description": "Scopes associated to teammate", - "items": {} - }, - "user_type": { - "type": "string", - "description": "Indicate the type of user: account owner, teammate admin user, or normal teammate", - "enum": [ - "admin", - "owner", - "teammate" - ] - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate has admin privileges" - }, - "phone": { - "type": "string", - "description": "(optional) Teammate's phone number" - }, - "website": { - "type": "string", - "description": "(optional) Teammate's website" - }, - "address": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "address2": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "city": { - "type": "string", - "description": "(optional) Teammate's city" - }, - "state": { - "type": "string", - "description": "(optional) Teammate's state" - }, - "zip": { - "type": "string", - "description": "(optional) Teammate's zip" - }, - "country": { - "type": "string", - "description": "(optional) Teammate's country" + "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": { + "$ref": "#/definitions/advanced_stats_clicks" + } + } + } + } } } }, "examples": { - "application/json": { - "username": "teammate1", - "first_name": "Jane", - "last_name": "Doe", - "email": "teammate1@example.com", - "scopes": [ - "user.profile.read", - "user.profile.update", - "..." - ], - "user_type": "admin", - "is_admin": true, - "phone": "123-345-3453", - "website": "www.example.com", - "company": "ACME Inc.", - "address": "123 Acme St", - "address2": "", - "city": "City", - "state": "CA", - "country": "USA", - "zip": "12345" - } + "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" + } + ] + } + ] } } }, @@ -18692,215 +28282,188 @@ "Authorization": [] } ] - }, - "patch": { - "operationId": "PATCH_v3-teammates-username", - "summary": "Update teammate's permissions", + } + }, + "/suppression/bounces": { + "get": { + "operationId": "GET_suppression-bounces", + "summary": "Retrieve all bounces", "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to update a teammate’s permissions.\n\nTo turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have.\n\n**Only the parent user or other admin teammates can update another teammate’s permissions.**\n\n**Admin users can only update permissions.**", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Bounces API" ], + "description": "**This endpoint allows you to retrieve all of your bounces.**", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "Provide list of scopes that should be given to teammate. If specifying list of scopes, is_admin should be set to False.", - "items": { - "type": "string" - } - }, - "is_admin": { - "type": "boolean", - "description": "Set to True if this teammate should be promoted to an admin user. If True, scopes should be an empty array." - } - }, - "required": [ - "scopes", - "is_admin" - ], - "example": { - "scopes": [ - "user.profile.read", - "user.profile.edit" - ], - "is_admin": false - } - } + "name": "start_time", + "in": "query", + "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", + "type": "integer" + }, + { + "name": "end_time", + "in": "query", + "description": "Refers end of the time range in unix timestamp when a bounce was created (inclusive).", + "type": "integer" + }, + { + "name": "Accept", + "in": "header", + "required": true, + "type": "string", + "default": "application/json" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Teammate's username" - }, - "first_name": { - "type": "string", - "description": "Teammate's first name" - }, - "last_name": { - "type": "string", - "description": "Teammate's last name" - }, - "email": { - "type": "string", - "description": "Teammate's email address" - }, - "scopes": { - "type": "array", - "description": "Scopes given to teammate", - "items": { - "type": "string" - } - }, - "user_type": { - "type": "string", - "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", - "enum": [ - "admin", - "owner", - "teammate" - ] - }, - "is_admin": { - "type": "boolean", - "description": "Set to true if teammate has admin priveleges" - }, - "phone": { - "type": "string", - "description": "(optional) Teammate's phone number" - }, - "website": { - "type": "string", - "description": "(optional) Teammate's website" - }, - "address": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "address2": { - "type": "string", - "description": "(optional) Teammate's address" - }, - "city": { - "type": "string", - "description": "(optional) Teammate's city" - }, - "state": { - "type": "string", - "description": "(optional) Teammate's state" - }, - "zip": { - "type": "string", - "description": "(optional) Teammate's zip" - }, - "country": { - "type": "string", - "description": "(optional) Teammate's country" - } + "type": "array", + "items": { + "$ref": "#/definitions/bounce_response" } }, "examples": { - "application/json": { - "username": "teammate1", - "first_name": "Jane", - "last_name": "Doe", - "email": "teammate1@example.com", - "scopes": [ - "user.profile.read", - "user.profile.edit" - ], - "user_type": "teammate", - "is_admin": false, - "phone": "123-345-3453", - "website": "www.example.com", - "company": "ACME Inc.", - "address": "123 Acme St", - "address2": "", - "city": "City", - "state": "CA", - "country": "USA", - "zip": "12345" - } + "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" + } + ] } }, - "400": { + "401": { "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_suppression-bounces", + "summary": "Delete bounces", + "tags": [ + "Bounces API" + ], + "description": "**This endpoint allows you to delete all emails on your bounces list.**\n\nThere are two options for deleting bounced emails: \n\n1. You can delete all bounced emails by setting `delete_all` to `true` in the request body. \n2. You can delete a selection of bounced emails by specifying the email addresses in the `emails` array of the request body.", + "parameters": [ + { + "name": "body", + "in": "body", "schema": { "type": "object", "properties": { - "errors": { + "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": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } + "type": "string" } } + }, + "example": { + "delete_all": false, + "emails": [ + "example@example.com", + "example2@example.com" + ] } + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "null" + } + }, + "401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { - "message": "one or more of given scopes are invalid", - "field": "scopes" + "field": null, + "message": "authorization required" } ] } } - }, - "404": { + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/suppression/bounces/{email}": { + "parameters": [ + { + "name": "email", + "in": "path", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_suppression-bounces-email", + "summary": "Retrieve a Bounce", + "tags": [ + "Bounces API" + ], + "description": "**This endpoint allows you to retrieve a specific bounce by email address.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { "description": "", "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } + "type": "array", + "items": { + "$ref": "#/definitions/bounce_response" } }, "examples": { - "application/json": { - "errors": [ - { - "message": "username not found", - "field": "username" - } - ] - } + "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" + } + ] } } }, @@ -18911,68 +28474,50 @@ ] }, "delete": { - "operationId": "DELETE_v3-teammates-username", - "summary": "Delete teammate", + "operationId": "DELETE_suppression-bounces-email", + "summary": "Delete a bounce", "tags": [ - "Teammates" - ], - "description": "This endpoint allows you to delete a teammate.\n\n**Only the parent user or an admin teammate can delete another teammate.**", - "consumes": [ - "application/json" + "Bounces API" ], - "produces": [ - "application/json" + "description": "**This endpoint allows you to remove an email address from your bounce list.**", + "parameters": [ + { + "name": "email_address", + "in": "query", + "description": "The email address you would like to remove from the bounce list.", + "required": true, + "type": "string", + "format": "email" + }, + { + "name": "body", + "in": "body", + "schema": { + "type": "null" + } + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } ], "responses": { "204": { "description": "", "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } + "type": "object" } }, - "404": { + "401": { "description": "", "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "field": { - "type": "string" - } - } - } - } - } + "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { - "message": "username not found", - "field": "username" + "field": null, + "message": "authorization required" } ] } @@ -18984,22 +28529,82 @@ "Authorization": [] } ] - } - }, - "/templates": { - "post": { - "operationId": "POST_templates", - "summary": "Create a transactional template.", + } + }, + "/suppression/blocks": { + "get": { + "operationId": "GET_suppression-blocks", + "summary": "Retrieve all blocks", + "tags": [ + "Blocks API" + ], + "description": "**This endpoint allows you to retrieve all email addresses that are currently on your blocks list.**", + "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "The start of the time range when a blocked email was created (inclusive). This is a unix timestamp.", + "type": "integer" + }, + { + "name": "end_time", + "in": "query", + "description": "The end of the time range when a blocked email was created (inclusive). This is a unix timestamp.", + "type": "integer" + }, + { + "name": "limit", + "in": "query", + "description": "Limit the number of results to be displayed per page.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "The point in the list to begin displaying results.", + "type": "integer" + }, + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/blocks-response" + }, + "examples": { + "application/json": [ + { + "created": 1443651154, + "email": "example@example.com", + "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", + "status": "4.0.0" + }, + { + "created": 1443651155, + "email": "example1@example.com", + "reason": "unable to resolve MX record for example.com: servfail", + "status": "4.0.0" + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_suppression-blocks", + "summary": "Delete blocks", "tags": [ - "Transactional Templates" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Blocks API" ], + "description": "**This endpoint allows you to delete all email addresses on your blocks list.**\n\nThere are two options for deleting blocked emails: \n\n1. You can delete all blocked emails by setting `delete_all` to `true` in the request body. \n2. You can delete a selection of blocked emails by specifying the email addresses in the `emails` array of the request body.", "parameters": [ { "name": "body", @@ -19007,17 +28612,24 @@ "schema": { "type": "object", "properties": { - "name": { - "type": "string", - "description": "The name for the new transactional template.", - "maxLength": 100 + "delete_all": { + "type": "boolean", + "description": "Indicates if you want to delete all blocked email addresses." + }, + "emails": { + "type": "array", + "description": "The specific blocked email addresses that you want to delete.", + "items": { + "type": "string" + } } }, - "required": [ - "name" - ], "example": { - "name": "example_name" + "delete_all": false, + "emails": [ + "example1@example.com", + "example2@example.com" + ] } } }, @@ -19026,17 +28638,59 @@ } ], "responses": { - "201": { + "204": { "description": "", "schema": { - "$ref": "#/definitions/transactional_template" + "type": "object", + "properties": {} + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/suppression/blocks/{email}": { + "parameters": [ + { + "name": "email", + "in": "path", + "description": "The email address of the specific block.", + "required": true, + "type": "string", + "format": "email" + } + ], + "get": { + "operationId": "GET_suppression-blocks-email", + "summary": "Retrieve a specific block", + "tags": [ + "Blocks API" + ], + "description": "**This endpoint allows you to retrieve a specific email address from your blocks list.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "$ref": "#/definitions/blocks-response" }, "examples": { - "application/json": { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "example_name", - "versions": [] - } + "application/json": [ + { + "created": 1443651154, + "email": "example@example.com", + "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", + "status": "4.0.0" + } + ] } } }, @@ -19046,29 +28700,24 @@ } ] }, - "get": { - "operationId": "GET_templates", - "summary": "Retrieve all transactional templates.", + "delete": { + "operationId": "DELETE_suppression-blocks-email", + "summary": "Delete a specific block", "tags": [ - "Transactional Templates" - ], - "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).", - "produces": [ - "application/json" + "Blocks API" ], + "description": "**This endpoint allows you to delete a specific email address from your blocks list.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "204": { "description": "", "schema": { - "type": "array", - "items": { - "$ref": "#/definitions/transactional_template" - } + "type": "object", + "properties": {} } } }, @@ -19079,27 +28728,39 @@ ] } }, - "/templates/{template_id}": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "description": "The id of the transactional template you want to retrieve.", - "required": true, - "type": "string" - } - ], + "/suppression/spam_reports": { "get": { - "operationId": "GET_templates-template_id", - "summary": "Retrieve a single transactional template.", + "operationId": "GET_suppression-spam_reports", + "summary": "Retrieve all spam reports", "tags": [ - "Transactional Templates" - ], - "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).", - "produces": [ - "application/json" + "Spam Reports API" ], + "description": "**This endpoint allows you to retrieve all spam reports.**", "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "The start of the time range when a spam report was created (inclusive). This is a unix timestamp.", + "type": "integer" + }, + { + "name": "end_time", + "in": "query", + "description": "The end of the time range when a spam report was created (inclusive). This is a unix timestamp.", + "type": "integer" + }, + { + "name": "limit", + "in": "query", + "description": "Limit the number of results to be displayed per page.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "Paging offset. The point in the list to begin displaying results.", + "type": "integer" + }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -19108,7 +28769,21 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/transactional_template" + "$ref": "#/definitions/spam-reports-response" + }, + "examples": { + "application/json": [ + { + "created": 1443651141, + "email": "user1@example.com", + "ip": "10.63.202.100" + }, + { + "created": 1443651154, + "email": "user2@example.com", + "ip": "10.63.202.100" + } + ] } } }, @@ -19118,19 +28793,13 @@ } ] }, - "patch": { - "operationId": "PATCH_templates-template_id", - "summary": "Edit a transactional template.", + "delete": { + "operationId": "DELETE_suppression-spam_reports", + "summary": "Delete spam reports", "tags": [ - "Transactional Templates" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Spam Reports API" ], + "description": "**This endpoint allows you to delete your spam reports.**\n\nDeleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.\n\nThere are two options for deleting spam reports: \n\n1. You can delete all spam reports by setting the `delete_all` field to `true` in the request body.\n2. You can delete a list of select spam reports by specifying the email addresses in the `emails` array of the request body.", "parameters": [ { "name": "body", @@ -19138,14 +28807,24 @@ "schema": { "type": "object", "properties": { - "name": { - "type": "string", - "description": "The name of the transactional template.", - "maxLength": 100 + "delete_all": { + "type": "boolean", + "description": "Indicates if you want to delete all email addresses on the spam report list." + }, + "emails": { + "type": "array", + "description": "A list of specific email addresses that you want to remove from the spam report list.", + "items": { + "type": "string" + } } }, "example": { - "name": "new_example_name" + "delete_all": false, + "emails": [ + "example1@example.com", + "example2@example.com" + ] } } }, @@ -19153,18 +28832,59 @@ "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object", + "properties": {} + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/suppression/spam_reports/{email}": { + "parameters": [ + { + "name": "email", + "in": "path", + "description": "The email address of a specific spam report that you want to retrieve.", + "required": true, + "type": "string", + "format": "email" + } + ], + "get": { + "operationId": "GET_suppression-spam_reports-email", + "summary": "Retrieve a specific spam report", + "tags": [ + "Spam Reports API" + ], + "description": "**This endpoint allows you to retrieve a specific spam report by email address.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], "responses": { "200": { "description": "", "schema": { - "$ref": "#/definitions/transactional_template" + "$ref": "#/definitions/spam-reports-response" }, "examples": { - "application/json": { - "id": "733ba07f-ead1-41fc-933a-3976baa23716", - "name": "new_example_name", - "versions": [] - } + "application/json": [ + { + "created": 1454433146, + "email": "test1@example.com", + "ip": "10.89.32.5" + } + ] } } }, @@ -19175,20 +28895,13 @@ ] }, "delete": { - "operationId": "DELETE_templates-template_id", - "summary": "Delete a template.", + "operationId": "DELETE_suppression-spam_reports-email", + "summary": "Delete a specific spam report", "tags": [ - "Transactional Templates" + "Spam Reports API" ], - "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).", + "description": "**This endpoint allows you to delete a specific spam report by email address.**\n\nDeleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -19197,7 +28910,8 @@ "204": { "description": "", "schema": { - "type": "object" + "type": "object", + "properties": {} } } }, @@ -19208,41 +28922,25 @@ ] } }, - "/templates/{template_id}/versions": { - "parameters": [ - { - "name": "template_id", - "in": "path", - "required": true, - "type": "string" - } - ], + "/asm/suppressions/global": { "post": { - "operationId": "POST_templates-template_id-versions", - "summary": "Create a new transactional template version.", + "operationId": "POST_asm-suppressions-global", + "summary": "Add recipient addresses to the global suppression group.", "tags": [ - "Transactional Templates Versions" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Suppressions - Global Suppressions" ], + "description": "**This endpoint allows you to add one or more email addresses to the global suppressions group.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/transactional_template_version", + "$ref": "#/definitions/suppressions-request", "example": { - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543", - "active": 1, - "name": "example_version_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>" + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] } } }, @@ -19256,33 +28954,25 @@ "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" + "recipient_emails": { + "type": "array", + "description": "The email addresses that are globally suppressed", + "items": { + "type": "string", + "format": "email" + } } }, "required": [ - "id", - "updated_at" + "recipient_emails" ] }, "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" + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] } } } @@ -19294,38 +28984,38 @@ ] } }, - "/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": { - "operationId": "POST_templates-template_id-versions-version_id-activate", - "summary": "Activate a transactional template version.", + "/suppression/unsubscribes": { + "get": { + "operationId": "GET_suppression-unsubscribes", + "summary": "Retrieve all global suppressions", "tags": [ - "Transactional Templates Versions" - ], - "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 |", - "produces": [ - "application/json" + "Suppressions - Global Suppressions" ], + "description": "**This endpoint allows you to retrieve a list of all email address that are globally suppressed.**", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + "name": "start_time", + "in": "query", + "description": "Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive).", + "type": "integer" + }, + { + "name": "end_time", + "in": "query", + "description": "Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive).", + "type": "integer" + }, + { + "name": "limit", + "in": "query", + "description": "The number of results to display on each page.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "The point in the list of results to begin displaying global suppressions.", + "type": "integer" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -19335,36 +29025,37 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." + "type": "array", + "items": { + "type": "object", + "properties": { + "created": { + "type": "integer", + "description": "A Unix timestamp indicating when the recipient was added to the global suppression list." + }, + "email": { + "type": "string", + "description": "The email address of the recipient who is globally suppressed.", + "format": "email" + } }, - "updated_at": { - "type": "string", - "description": "The date and time that the version was last updated." + "required": [ + "created", + "email" + ] + } + }, + "examples": { + "application/json": [ + { + "created": 1443651141, + "email": "user1@example.com" }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_template_version" + { + "created": 1443651154, + "email": "user2@example.com" } - }, - "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" - } } } }, @@ -19375,31 +29066,23 @@ ] } }, - "/templates/{template_id}/versions/{version_id}": { + "/asm/suppressions/global/{email}": { "parameters": [ { - "name": "template_id", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "version_id", + "name": "email", "in": "path", + "description": "The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.", "required": true, "type": "string" } ], "get": { - "operationId": "GET_templates-template_id-versions-version_id", - "summary": "Retrieve a specific transactional template version.", + "operationId": "GET_asm-suppressions-global-email", + "summary": "Retrieve a Global Suppression", "tags": [ - "Transactional Templates Versions" - ], - "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 |", - "produces": [ - "application/json" + "Suppressions - Global Suppressions" ], + "description": "**This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.**\n\nIf the email address you include in the URL path parameter `{email}` is already globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -19409,35 +29092,22 @@ "200": { "description": "", "schema": { + "title": "Retrieve a Global Suppression response", "type": "object", "properties": { - "id": { - "type": "string", - "description": "The ID of the template version." - }, - "updated_at": { + "recipient_email": { "type": "string", - "description": "The date and time that the template version was last updated." - }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_template_version" + "description": "The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed.", + "format": "email" } }, "required": [ - "id", - "updated_at" + "recipient_email" ] }, "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" + "recipient_email": "test@example.com" } } } @@ -19448,53 +29118,51 @@ } ] }, - "patch": { - "operationId": "PATCH_templates-template_id-versions-version_id", - "summary": "Edit a transactional template version.", + "delete": { + "operationId": "DELETE_asm-suppressions-global-email", + "summary": "Delete a Global Suppression", "tags": [ - "Transactional Templates Versions" - ], - "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 |", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Suppressions - Global Suppressions" ], + "description": "**This endpoint allows you to remove an email address from the global suppressions group.**\n\nDeleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", "parameters": [ { - "name": "body", - "in": "body", + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", "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." - } - }, + "type": "object" + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/asm/groups": { + "post": { + "operationId": "POST_asm-groups", + "summary": "Create a new suppression group", + "tags": [ + "Suppressions - Unsubscribe Groups" + ], + "description": "**This endpoint allows you to create a new suppression group.**\n\nTo add an email address to the suppression group, [create a Suppression](https://sendgrid.api-docs.io/v3.0/suppressions-suppressions/add-suppressions-to-a-suppression-group).", + "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/suppression-group-request-base", "example": { - "active": 1, - "name": "updated_example_name", - "html_content": "<%body%>", - "plain_content": "<%body%>", - "subject": "<%subject%>" + "name": "Product Suggestions", + "description": "Suggestions for products our users might like.", + "is_default": true } } }, @@ -19503,38 +29171,41 @@ } ], "responses": { - "200": { + "201": { "description": "", "schema": { "type": "object", "properties": { "id": { + "type": "integer", + "description": "The ID of the suppression group." + }, + "name": { "type": "string", - "description": "The ID of the template version." + "description": "The name of the suppression group." }, - "updated_at": { + "description": { "type": "string", - "description": "The date and time that the template version was last updated." + "description": "A brief description of the suppression group." }, - "Transactional Template Version": { - "$ref": "#/definitions/transactional_template_version" + "is_default": { + "type": "boolean", + "description": "Indicates if this is the default suppression group." } }, "required": [ "id", - "updated_at" + "name", + "description", + "is_default" ] }, "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" + "id": 103, + "name": "Product Suggestions", + "description": "Suggestions for products our users might like.", + "is_default": false } } } @@ -19545,30 +29216,51 @@ } ] }, - "delete": { - "operationId": "DELETE_templates-template_id-versions-version_id", - "summary": "Delete a transactional template version.", + "get": { + "operationId": "GET_asm-groups", + "summary": "Retrieve all suppression groups associated with the user.", "tags": [ - "Transactional Templates Versions" + "Suppressions - Unsubscribe Groups" ], - "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 |", + "description": "**This endpoint allows you to retrieve a list of all suppression groups created by this user.**\n\nThis endpoint can also return information for multiple group IDs that you include in your request. To add a group ID to your request, simply append `?id=123456&id=123456`, with the appropriate group IDs.", "parameters": [ { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + "name": "id", + "in": "query", + "type": "integer" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "null" + "type": "array", + "items": { + "$ref": "#/definitions/suppression_group" + } + }, + "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 + } + ] } } }, @@ -19579,17 +29271,23 @@ ] } }, - "/user/profile": { + "/asm/groups/{group_id}": { + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the suppression group you would like to retrieve.", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_user-profile", - "summary": "Get a user's profile", + "operationId": "GET_asm-groups-group_id", + "summary": "Get information on a single suppression group.", "tags": [ - "Users API" - ], - "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)", - "produces": [ - "application/json" + "Suppressions - Unsubscribe Groups" ], + "description": "**This endpoint allows you to retrieve a single suppression group.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -19599,80 +29297,42 @@ "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." + "allOf": [ + { + "$ref": "#/definitions/suppression-group-request-base" }, - "zip": { - "type": "string", - "description": "The user's zip code." + { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the suppression group." + }, + "unsubscribes": { + "type": "integer", + "description": "The number of unsubscribes, or suppressions, in this group." + }, + "last_email_sent_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id" + ] } - }, - "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" + "description": "Our monthly newsletter.", + "id": 100, + "is_default": true, + "last_email_sent_at": null, + "name": "Newsletters", + "unsubscribes": 400 } } } @@ -19684,28 +29344,26 @@ ] }, "patch": { - "operationId": "PATCH_user-profile", - "summary": "Update a user's profile", + "operationId": "PATCH_asm-groups-group_id", + "summary": "Update a suppression group.", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to update your current profile details.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)\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.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Suppressions - Unsubscribe Groups" ], + "description": "**This endpoint allows you to update or change a suppression group.**", "parameters": [ { "name": "body", "in": "body", "schema": { - "$ref": "#/definitions/user_profile", + "allOf": [ + { + "$ref": "#/definitions/suppression-group-request-base" + } + ], "example": { - "first_name": "Example", - "last_name": "User", - "city": "Orange" + "id": 103, + "name": "Item Suggestions", + "description": "Suggestions for items our users might like." } } }, @@ -19714,41 +29372,43 @@ } ], "responses": { - "200": { + "201": { "description": "", "schema": { - "$ref": "#/definitions/user_profile" + "$ref": "#/definitions/suppression_group" }, "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" + "id": 103, + "name": "Item Suggestions", + "description": "Suggestions for items our users might like." } } - }, - "401": { - "description": "", - "schema": { - "$ref": "#/definitions/global:ErrorResponse" - }, - "examples": { - "application/json": { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } + } + }, + "security": [ + { + "Authorization": [] + } + ] + }, + "delete": { + "operationId": "DELETE_asm-groups-group_id", + "summary": "Delete a Suppression Group", + "tags": [ + "Suppressions - Unsubscribe Groups" + ], + "description": "**This endpoint allows you to delete a suppression group.**\n\nIf a recipient uses the \"one-click unsubscribe\" option on an email associated with a deleted group, that recipient will be added to the global suppression list.\n\nDeleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", + "schema": { + "type": "object" } } }, @@ -19759,51 +29419,63 @@ ] } }, - "/user/account": { - "get": { - "operationId": "GET_user-account", - "summary": "Get a user's account information.", + "/asm/groups/{group_id}/suppressions": { + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The id of the unsubscribe group that you are adding suppressions to.", + "required": true, + "type": "string" + } + ], + "post": { + "operationId": "POST_asm-groups-group_id-suppressions", + "summary": "Add suppressions to a suppression group", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to retrieve your user account details.**\n\nYour user's account information includes the user's account type and reputation.\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", - "produces": [ - "application/json" + "Suppressions - Suppressions" ], + "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.", "parameters": [ + { + "name": "body", + "in": "body", + "schema": { + "$ref": "#/definitions/suppressions-request", + "example": { + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] + } + } + }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "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." + "recipient_emails": { + "type": "array", + "description": "The email addresses you added to the unsubscribe group", + "items": { + "type": "string", + "format": "email" + } } - }, - "required": [ - "type", - "reputation" - ] + } }, "examples": { "application/json": { - "reputation": 100, - "type": "paid" + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] } } } @@ -19813,19 +29485,14 @@ "Authorization": [] } ] - } - }, - "/user/email": { + }, "get": { - "operationId": "GET_user-email", - "summary": "Retrieve your account email address", + "operationId": "GET_asm-groups-group_id-suppressions", + "summary": "Retrieve all suppressions for a suppression group", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to retrieve the email address currently on file for your account.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", - "produces": [ - "application/json" + "Suppressions - Suppressions" ], + "description": "**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -19835,21 +29502,18 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address currently on file for your account." - } - }, - "required": [ - "email" - ] + "type": "array", + "description": "The list of email addresses belonging to the given suppression group.", + "items": { + "type": "string", + "format": "email" + } }, "examples": { - "application/json": { - "email": "test@example.com" - } + "application/json": [ + "example@example.com", + "example2@example.com" + ] } } }, @@ -19858,34 +29522,37 @@ "Authorization": [] } ] - }, - "put": { - "operationId": "PUT_user-email", - "summary": "Update your account email address", + } + }, + "/asm/groups/{group_id}/suppressions/search": { + "parameters": [ + { + "name": "group_id", + "in": "path", + "description": "The ID of the suppression group that you would like to search.", + "required": true, + "type": "string" + } + ], + "post": { + "operationId": "POST_asm-groups-group_id-suppressions-search", + "summary": "Search for suppressions within a group", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to update the email address currently on file for your account.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Suppressions - Suppressions" ], + "description": "**This endpoint allows you to search a suppression group for multiple suppressions.**\n\nWhen given a list of email addresses and a group ID, this endpoint will only return the email addresses that have been unsubscribed from the given group.", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The new email address that you would like to use for your account." - } - }, + "$ref": "#/definitions/suppressions-request", "example": { - "email": "example@example.com" + "recipient_emails": [ + "exists1@example.com", + "exists2@example.com", + "doesnotexists@example.com" + ] } } }, @@ -19897,15 +29564,17 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The current email address on file for your account." - } - }, - "required": [ - "email" + "type": "array", + "description": "The email address from your search that do exist in the suppression group.", + "items": { + "type": "string", + "format": "email" + } + }, + "examples": { + "application/json": [ + "exists1@example.com", + "exists2@example.com" ] } } @@ -19917,17 +29586,14 @@ ] } }, - "/user/username": { + "/asm/suppressions": { "get": { - "operationId": "GET_user-username", - "summary": "Retrieve your username", + "operationId": "GET_asm-suppressions", + "summary": "Retrieve all suppressions", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to retrieve your current account username.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", - "produces": [ - "application/json" + "Suppressions - Suppressions" ], + "description": "**This endpoint allows you to retrieve a list of all suppressions.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -19937,26 +29603,160 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "Your account username." + "type": "array", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address that was suppressed." + }, + "group_id": { + "type": "integer", + "description": "The id of the suppression group that this email address belongs to." + }, + "group_name": { + "type": "string", + "description": "The name of the suppression group that this email address belongs to." + }, + "created_at": { + "type": "integer", + "description": "A UNIX timestamp indicating when the suppression was created." + } }, - "user_id": { - "type": "integer", - "description": "The user ID for your account." + "required": [ + "email", + "group_id", + "group_name", + "created_at" + ] + } + }, + "examples": { + "application/json": [ + { + "email": "test1@example.com", + "group_id": 1, + "group_name": "Weekly News", + "created_at": 1410986704 + }, + { + "email": "test1@example.com", + "group_id": 2, + "group_name": "Daily News", + "created_at": 1411493671 + }, + { + "email": "test2@example.com", + "group_id": 2, + "group_name": "Daily News", + "created_at": 1411493671 + } + ] + } + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/asm/suppressions/{email}": { + "parameters": [ + { + "name": "email", + "in": "path", + "description": "The email address that you want to search suppression groups for.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_asm-suppressions-email", + "summary": "Retrieve all suppression groups for an email address", + "tags": [ + "Suppressions - Suppressions" + ], + "description": "**This endpoint returns a list of all groups from which the given email address has been unsubscribed.**", + "parameters": [ + { + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "suppressions": { + "type": "array", + "description": "The array of suppression groups.", + "items": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "The description of the suppression group." + }, + "id": { + "type": "integer", + "description": "The id of the suppression group." + }, + "is_default": { + "type": "boolean", + "description": "Indicates if the suppression group is set as the default." + }, + "name": { + "type": "string", + "description": "The name of the suppression group." + }, + "suppressed": { + "type": "boolean", + "description": "Indicates if the given email address is suppressed for this group." + } + }, + "required": [ + "description", + "id", + "is_default", + "name", + "suppressed" + ] + } } }, "required": [ - "username", - "user_id" + "suppressions" ] }, "examples": { "application/json": { - "username": "test_username", - "user_id": 1 + "suppressions": [ + { + "description": "Optional description.", + "id": 1, + "is_default": true, + "name": "Weekly News", + "suppressed": true + }, + { + "description": "Some daily news.", + "id": 2, + "is_default": true, + "name": "Daily News", + "suppressed": true + }, + { + "description": "An old group.", + "id": 2, + "is_default": false, + "name": "Old News", + "suppressed": false + } + ] } } } @@ -19966,60 +29766,42 @@ "Authorization": [] } ] - }, - "put": { - "operationId": "PUT_user-username", - "summary": "Update your username", + } + }, + "/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": { + "operationId": "DELETE_asm-groups-group_id-suppressions-email", + "summary": "Delete a suppression from a suppression group", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to update the username for your account.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Suppressions - Suppressions" ], + "description": "**This endpoint allows you to remove a suppressed email address from the given suppression group.**\n\nRemoving an address will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required.", "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The new username you would like to use for your account." - } - }, - "example": { - "username": "test_username" - } - } - }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "204": { "description": "", "schema": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The current username on file for your account." - } - }, - "required": [ - "username" - ] - }, - "examples": { - "application/json": { - "username": "test_username" - } + "type": "null" } } }, @@ -20030,18 +29812,39 @@ ] } }, - "/user/credits": { + "/suppression/invalid_emails": { "get": { - "operationId": "GET_user-credits", - "summary": "Retrieve your credit balance", + "operationId": "GET_suppression-invalid_emails", + "summary": "Retrieve all invalid emails", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to retrieve the current credit balance for your account.**\n\nYour monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html).", - "produces": [ - "application/json" + "Invalid Emails API" ], + "description": "**This endpoint allows you to retrieve a list of all invalid email addresses.**", "parameters": [ + { + "name": "start_time", + "in": "query", + "description": "Refers start of the time range in unix timestamp when an invalid email was created (inclusive).", + "type": "integer" + }, + { + "name": "end_time", + "in": "query", + "description": "Refers end of the time range in unix timestamp when an invalid email was created (inclusive).", + "type": "integer" + }, + { + "name": "limit", + "in": "query", + "description": "Limit the number of results to be displayed per page.", + "type": "integer" + }, + { + "name": "offset", + "in": "query", + "description": "Paging offset. The point in the list to begin displaying results.", + "type": "integer" + }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -20050,57 +29853,25 @@ "200": { "description": "", "schema": { - "type": "object", - "properties": { - "remain": { - "type": "integer", - "description": "The remaining number of credits available on your account." - }, - "total": { - "type": "integer", - "description": "The total number of credits assigned to your account." - }, - "overage": { - "type": "integer", - "description": "The number of overdrawn credits for your account." - }, - "used": { - "type": "integer", - "description": "The number of credits that you have used." - }, - "last_reset": { - "type": "string", - "description": "The date that your credit balance was last reset." - }, - "next_reset": { - "type": "string", - "description": "The next date that your credit balance will be reset." + "type": "array", + "description": "The list of invalid email addresses.", + "items": { + "$ref": "#/definitions/invalid-email" + } + }, + "examples": { + "application/json": [ + { + "created": 1449953655, + "email": "user1@example.com", + "reason": "Mail domain mentioned in email address is unknown" }, - "reset_frequency": { - "type": "string", - "description": "The frequency at which your credit balance will be reset." + { + "created": 1449939373, + "email": "user2@example.com", + "reason": "Mail domain mentioned in email address is unknown" } - }, - "required": [ - "remain", - "total", - "overage", - "used", - "last_reset", - "next_reset", - "reset_frequency" ] - }, - "examples": { - "application/json": { - "remain": 200, - "total": 200, - "overage": 0, - "used": 0, - "last_reset": "2013-01-01", - "next_reset": "2013-02-01", - "reset_frequency": "monthly" - } } } }, @@ -20109,19 +29880,14 @@ "Authorization": [] } ] - } - }, - "/user/password": { - "put": { - "operationId": "PUT_user-password", - "summary": "Update your password", + }, + "delete": { + "operationId": "DELETE_suppression-invalid_emails", + "summary": "Delete invalid emails", "tags": [ - "Users API" - ], - "description": "**This endpoint allows you to update your password.**\n\nKeeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to.\n\nFor more information about your user profile:\n\n* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html)", - "produces": [ - "application/json" + "Invalid Emails API" ], + "description": "**This endpoint allows you to remove email addresses from your invalid email address list.**\n\nThere are two options for deleting invalid email addresses: \n\n1) You can delete all invalid email addresses by setting `delete_all` to true in the request body.\n2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body.", "parameters": [ { "name": "body", @@ -20129,22 +29895,25 @@ "schema": { "type": "object", "properties": { - "new_password": { - "type": "string", - "description": "The new password you would like to use for your account." - }, - "old_password": { - "type": "string", - "description": "The old password for your account." + "delete_all": { + "type": "boolean", + "description": "Indicates if you want to remove all email address from the invalid emails list." + }, + "emails": { + "type": "array", + "description": "The list of specific email addresses that you want to remove.", + "items": { + "type": "string", + "format": "email" + } } }, - "required": [ - "new_password", - "old_password" - ], "example": { - "new_password": "new_password", - "old_password": "old_password" + "delete_all": false, + "emails": [ + "example1@example.com", + "example2@example.com" + ] } } }, @@ -20153,7 +29922,7 @@ } ], "responses": { - "200": { + "204": { "description": "", "schema": { "type": "object", @@ -20168,17 +29937,23 @@ ] } }, - "/user/webhooks/event/settings": { + "/suppression/invalid_emails/{email}": { + "parameters": [ + { + "name": "email", + "in": "path", + "description": "The specific email address of the invalid email entry that you want to retrieve.", + "required": true, + "type": "string" + } + ], "get": { - "operationId": "GET_user-webhooks-event-settings", - "summary": "Retrieve Event Webhook settings", + "operationId": "GET_suppression-invalid_emails-email", + "summary": "Retrieve a specific invalid email", "tags": [ - "Webhooks" - ], - "description": "**This endpoint allows you to retrieve your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", - "produces": [ - "application/json" + "Invalid Emails API" ], + "description": "**This endpoint allows you to retrieve a specific invalid email addresses.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" @@ -20188,24 +29963,22 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/event_webhook_settings" + "type": "array", + "description": "A specific invalid email.", + "minItems": 0, + "maxItems": 1, + "items": { + "$ref": "#/definitions/invalid-email" + } }, "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 - } + "application/json": [ + { + "created": 1454433146, + "email": "test1@example.com", + "reason": "Mail domain mentioned in email address is unknown" + } + ] } } }, @@ -20215,42 +29988,52 @@ } ] }, - "patch": { - "operationId": "PATCH_user-webhooks-event-settings", - "summary": "Update Event Notification Settings", + "delete": { + "operationId": "DELETE_suppression-invalid_emails-email", + "summary": "Delete a specific invalid email", "tags": [ - "Webhooks" - ], - "description": "**This endpoint allows you to update your current event webhook settings.**\n\nIf an event type is marked as `true`, then the event webhook will include information about that event.\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" + "Invalid Emails API" ], + "description": "**This endpoint allows you to remove a specific email address from the invalid email address list.**", "parameters": [ { - "name": "body", - "in": "body", + "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + } + ], + "responses": { + "204": { + "description": "", "schema": { - "$ref": "#/definitions/event_webhook_settings", - "example": { - "enabled": true, - "url": "url", - "group_resubscribe": true, - "delivered": true, - "group_unsubscribe": true, - "spam_report": true, - "bounce": true, - "deferred": true, - "unsubscribe": true, - "processed": true, - "open": true, - "click": true, - "dropped": true - } + "type": "object", + "properties": {} } - }, + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + }, + "/user/webhooks/parse/settings/{hostname}": { + "parameters": [ + { + "name": "hostname", + "in": "path", + "description": "The hostname associated with the inbound parse setting that you would like to retrieve.", + "required": true, + "type": "string" + } + ], + "get": { + "operationId": "GET_user-webhooks-parse-settings-hostname", + "summary": "Retrieve a specific parse setting", + "tags": [ + "Settings - Inbound Parse" + ], + "description": "**This endpoint allows you to retrieve a specific inbound parse setting by hostname.**\n\nYou can retrieve all your Inbound Parse settings and their associated host names with the #endpoint:b8xyiHYsGatArCnSt endpoint.", + "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } @@ -20259,25 +30042,28 @@ "200": { "description": "", "schema": { - "$ref": "#/definitions/event_webhook_settings" + "$ref": "#/definitions/parse-setting" }, "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 + "url": "http://mydomain.com/parse", + "hostname": "mail.mydomain.com", + "spam_check": true, + "send_raw": true } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -20285,33 +30071,24 @@ "Authorization": [] } ] - } - }, - "/user/webhooks/event/test": { - "post": { - "operationId": "POST_user-webhooks-event-test", - "summary": "Test Event Notification Settings", + }, + "patch": { + "operationId": "PATCH_user-webhooks-parse-settings-hostname", + "summary": "Update a parse setting", "tags": [ - "Webhooks" - ], - "description": "**This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.**\n\nSendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email.\n\nCommon uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program.", - "produces": [ - "application/json" + "Settings - Inbound Parse" ], + "description": "**This endpoint allows you to update a specific inbound parse setting by hostname.**\n\nYou can retrieve all your Inbound Parse settings and their associated host names with the #endpoint:b8xyiHYsGatArCnSt endpoint.", "parameters": [ { "name": "body", "in": "body", "schema": { - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "The URL where you would like the test notification to be sent." - } - }, + "$ref": "#/definitions/parse-setting", "example": { - "url": "url" + "url": "http://newdomain.com/parse", + "spam_check": false, + "send_raw": true } } }, @@ -20320,11 +30097,31 @@ } ], "responses": { - "204": { + "200": { "description": "", "schema": { - "type": "object" + "$ref": "#/definitions/parse-setting" + }, + "examples": { + "application/json": { + "url": "http://mydomain.com/parse", + "hostname": "mail.mydomain.com", + "spam_check": true, + "send_raw": true + } } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ @@ -20332,3230 +30129,4157 @@ "Authorization": [] } ] - } - }, - "/user/webhooks/parse/stats": { - "get": { - "operationId": "GET_user-webhooks-parse-stats", - "summary": "Retrieves Inbound Parse Webhook statistics.", + }, + "delete": { + "operationId": "DELETE_user-webhooks-parse-settings-hostname", + "summary": "Delete a parse setting", "tags": [ - "Webhooks" - ], - "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).", - "produces": [ - "application/json" + "Settings - Inbound Parse" ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The number of statistics to return on each page.", - "required": false, - "type": "string" - }, - { - "name": "offset", - "in": "query", - "description": "The number of statistics to skip.", - "required": false, - "type": "string" - }, - { - "name": "aggregated_by", - "in": "query", - "description": "How you would like the statistics to by grouped. ", - "required": false, - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - }, - { - "name": "start_date", - "in": "query", - "description": "The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", - "required": true, - "type": "string" - }, - { - "name": "end_date", - "in": "query", - "description": "The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD", - "required": false, - "type": "string", - "default": "The day the request is made." - }, + "description": "**This endpoint allows you to delete a specific inbound parse setting by hostname.**\n\nYou can retrieve all your Inbound Parse settings and their associated host names with the #endpoint:b8xyiHYsGatArCnSt endpoint.", + "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { - "200": { + "204": { "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 - } - } - ] + "type": "object" + } + }, + "401": { + "$ref": "#/responses/trait:globalErrors:401" + }, + "403": { + "$ref": "#/responses/trait:globalErrors:403" + }, + "404": { + "$ref": "#/responses/trait:globalErrors:404" + }, + "500": { + "$ref": "#/responses/trait:globalErrors:500" + } + }, + "security": [ + { + "Authorization": [] + } + ] + } + } + }, + "parameters": { + "trait:onBehalfOfSubuser:on-behalf-of": { + "name": "on-behalf-of", + "in": "header", + "type": "string", + "default": "The subuser's username. This header generates the API call as if the subuser account was making the call." + }, + "trait:baseParams:aggregated_by": { + "name": "aggregated_by", + "in": "query", + "description": "Dictates how the stats are time-sliced. Currently, `\"total\"` and `\"day\"` are supported.", + "type": "string", + "default": "total", + "enum": [ + "day", + "total" + ] + }, + "trait:baseParams:start_date": { + "name": "start_date", + "in": "query", + "description": "Format: `YYYY-MM-DD`. If this parameter is included, the stats' start date is included in the search.", + "type": "string", + "format": "date", + "default": "" + }, + "trait:baseParams:end_date": { + "name": "end_date", + "in": "query", + "description": "Format: `YYYY-MM-DD`.If this parameter is included, the stats' end date is included in the search.", + "type": "string", + "default": "", + "format": "date" + }, + "trait:baseParams:timezone": { + "name": "timezone", + "in": "query", + "description": "[IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented, e.g., \"America/Chicago\".", + "type": "string", + "default": "UTC" + }, + "trait:pagination:page_size": { + "name": "page_size", + "in": "query", + "description": "The number of elements you want returned on each page.", + "type": "integer", + "default": 50, + "minimum": 1, + "maximum": 100 + }, + "trait:pagination:page_token": { + "name": "page_token", + "in": "query", + "description": "The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn't exist, you're at the first page. Similarly, if `_metadata.next` is not present, you're at the last page.", + "type": "string" + }, + "trait:singlesendQueryParams:group_by": { + "name": "group_by", + "in": "query", + "description": "A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.", + "type": "array", + "enum": [ + "ab_variation", + "ab_phase" + ], + "items": { + "type": "string" + } + }, + "trait:automationQueryParams:group_by": { + "name": "group_by", + "in": "query", + "description": "Automations can have multiple steps. Including `step_id` as a `group_by` metric allows further granularity of stats.", + "type": "array", + "enum": [ + "step_id" + ], + "items": { + "type": "string" + } + }, + "trait:automationQueryParams:step_ids": { + "name": "step_ids", + "in": "query", + "description": "Comma-separated list of `step_ids` that you want the link stats for.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "format": "uuid" + } + }, + "trait:singlesendQueryParams2:group_by": { + "name": "group_by", + "in": "query", + "description": "A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields.", + "type": "array", + "enum": [ + "ab_variation", + "ab_phase" + ], + "items": { + "type": "string" + } + }, + "trait:singlesendQueryParams2:ab_variation_id": { + "name": "ab_variation_id", + "in": "query", + "type": "string", + "format": "uuid" + }, + "trait:singlesendQueryParams2:ab_phase_id": { + "name": "ab_phase_id", + "in": "query", + "type": "string", + "enum": [ + "test", + "send" + ] + }, + "trait:statsAdvancedStatsBaseQueryStrings:start_date": { + "name": "start_date", + "in": "query", + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "required": true, + "type": "string" + }, + "trait:statsAdvancedStatsBaseQueryStrings:end_date": { + "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" + }, + "trait:statsAdvancedStatsBaseQueryStrings:aggregated_by": { + "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" + ] + }, + "trait:statsAdvancedQueryStringsLimitOffset:limit": { + "name": "limit", + "in": "query", + "description": "The number of results to return.", + "required": false, + "type": "integer" + }, + "trait:statsAdvancedQueryStringsLimitOffset:offset": { + "name": "offset", + "in": "query", + "description": "The point in the list to begin retrieving results.", + "required": false, + "type": "integer" + }, + "trait:statsAdvancedQueryStringsLimitOffset:aggregated_by": { + "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" + ] + }, + "trait:statsAdvancedQueryStringsLimitOffset:start_date": { + "name": "start_date", + "in": "query", + "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", + "required": true, + "type": "string" + }, + "trait:statsAdvancedQueryStringsLimitOffset:end_date": { + "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" + }, + "trait:designsQueryStrings:page_size": { + "name": "page_size", + "in": "query", + "description": "number of results to return", + "type": "integer", + "minimum": 0, + "default": 100 + }, + "trait:designsQueryStrings:page_token": { + "name": "page_token", + "in": "query", + "description": "token corresponding to a specific page of results, as provided by metadata", + "type": "string" + }, + "trait:designsQueryStrings:summary": { + "name": "summary", + "in": "query", + "description": "set to false to return all fields", + "type": "boolean", + "default": "true" + }, + "trait:authorizationHeader:Authorization": { + "name": "Authorization", + "in": "header", + "required": true, + "type": "string", + "default": "Bearer <>" + } + }, + "responses": { + "trait:errorResponse:400": { + "description": "", + "schema": { + "$ref": "#/definitions/error_schema" + } + }, + "trait:pagination:200": { + "description": "", + "schema": { + "type": "object", + "properties": { + "_metadata": { + "$ref": "#/definitions/metadata" + } + } + } + }, + "trait:mailSendErrors:400": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:mailSendErrors:413": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:globalErrors:401": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:globalErrors:403": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:globalErrors:404": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:globalErrors:500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + }, + "trait:cancelScheduledSendsErrors:400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" }, - { - "date": "2015-10-26", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "field": { + "type": "string" }, - { - "date": "2015-10-27", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "help": { + "type": "object" + } + } + } + }, + "id": { + "type": "string" + } + } + } + }, + "trait:apiKeysErrors:400": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:apiKeysErrors:403": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:apiKeysErrors:404": { + "description": "", + "schema": { + "$ref": "#/definitions/global_error_response_schema" + } + }, + "trait:makoErrorResponse:400": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "error_id": { + "type": "string", + "description": "The ID associated with the error." }, - { - "date": "2015-10-28", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "field": { + "type": [ + "string", + "null" + ], + "description": "The field that generated the error." }, - { - "date": "2015-10-29", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "message": { + "type": "string", + "description": "The error message." }, - { - "date": "2015-10-30", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "parameter": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + } + } + }, + "trait:makoErrorResponse:401": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "error_id": { + "type": "string", + "description": "The ID associated with the error." }, - { - "date": "2015-10-31", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "field": { + "type": [ + "string", + "null" + ], + "description": "The field that generated the error." }, - { - "date": "2015-11-01", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "message": { + "type": "string", + "description": "The error message." }, - { - "date": "2015-11-02", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "parameter": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + } + } + }, + "trait:makoErrorResponse:403": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "error_id": { + "type": "string", + "description": "The ID associated with the error." }, - { - "date": "2015-11-03", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "field": { + "type": [ + "string", + "null" + ], + "description": "The field that generated the error." }, - { - "date": "2015-11-04", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "message": { + "type": "string", + "description": "The error message." }, - { - "date": "2015-11-05", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "parameter": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + } + } + }, + "trait:makoErrorResponse:404": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "error_id": { + "type": "string", + "description": "The ID associated with the error." }, - { - "date": "2015-11-06", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "field": { + "type": [ + "string", + "null" + ], + "description": "The field that generated the error." }, - { - "date": "2015-11-07", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "message": { + "type": "string", + "description": "The error message." }, - { - "date": "2015-11-08", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "parameter": { + "type": "string" + } + }, + "required": [ + "message" + ] + } + } + } + } + }, + "trait:makoErrorResponse:500": { + "description": "", + "schema": { + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "error_id": { + "type": "string", + "description": "The ID associated with the error." }, - { - "date": "2015-11-09", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "field": { + "type": [ + "string", + "null" + ], + "description": "The field that generated the error." }, - { - "date": "2015-11-10", - "stats": [ - { - "metrics": { - "received": 0 - } - } - ] + "message": { + "type": "string", + "description": "The error message." + }, + "parameter": { + "type": "string" } + }, + "required": [ + "message" ] } } + } + } + }, + "trait:singleSignOnErrorsTrait:400": { + "description": "", + "schema": { + "$ref": "#/definitions/sso-error-response" + } + }, + "trait:singleSignOnErrorsTrait:401": { + "description": "", + "schema": { + "$ref": "#/definitions/sso-error-response" + } + }, + "trait:singleSignOnErrorsTrait:403": { + "description": "", + "schema": { + "$ref": "#/definitions/sso-error-response" + } + }, + "trait:singleSignOnErrorsTrait:429": { + "description": "", + "schema": { + "$ref": "#/definitions/sso-error-response" + } + }, + "trait:singleSignOnErrorsTrait:500": { + "description": "", + "schema": { + "$ref": "#/definitions/sso-error-response" + } + } + }, + "definitions": { + "partner_settings_new_relic": { + "title": "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" + ] + }, + "subscription_tracking_settings": { + "title": "Settings: Subscription Tracking", + "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.", + "format": "uri" + } + } + }, + "contactdb_recipient_response": { + "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" + ], + "example": { + "error_count": 1, + "error_indices": [ + 2 + ], + "new_count": 2, + "persisted_recipients": [ + "YUBh", + "bWlsbGVyQG1pbGxlci50ZXN0" + ], + "updated_count": 0, + "errors": [ + { + "message": "Invalid email.", + "error_indices": [ + 2 + ] + } + ] + } + }, + "campaign_response": { + "title": "Campaigns 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_conditions": { + "title": "ContactDB: Segments: Conditions", + "type": "object", + "properties": { + "field": { + "type": "string" }, - "security": [ - { - "Authorization": [] - } - ] + "value": { + "type": "string" + }, + "operator": { + "type": "string", + "enum": [ + "eq", + "ne", + "lt", + "gt", + "contains" + ] + }, + "and_or": { + "type": "string", + "enum": [ + "and", + "or", + "" + ] + } + }, + "required": [ + "field", + "value", + "operator" + ] + }, + "bounce_response": { + "title": "Bounce Response", + "type": "object", + "properties": { + "created": { + "type": "number", + "description": "The unix timestamp for when the bounce record was created at SendGrid." + }, + "email": { + "type": "string", + "format": "email", + "description": "The email address that was added to the bounce list." + }, + "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" + } + }, + "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" } }, - "/whitelabel/domains": { - "get": { - "operationId": "GET_whitelabel-domains", - "summary": "List all domain whitelabels.", - "tags": [ - "Whitelabel - Domains" - ], - "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)", - "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" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" - ] + "contacts": { + "title": "Contacts", + "type": "object", + "properties": { + "address": { + "type": "string" + }, + "address2": { + "type": "object" + }, + "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" + } + } + }, + "reverse_dns": { + "title": "Reverse DNS", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the Reverse DNS." + }, + "ip": { + "type": "string", + "description": "The IP address that this Reverse DNS was created for." + }, + "rdns": { + "type": "string", + "description": "The reverse DNS record for the IP address. This points to the Reverse DNS subdomain." + }, + "users": { + "type": "array", + "description": "The users who are able to send mail from the IP address.", + "items": { + "type": "object", + "properties": { + "username": { + "type": "string", + "description": "The username of a user who can send mail from the IP address." + }, + "user_id": { + "type": "integer", + "description": "The ID of a user who can send mail from the IP address." } }, - "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 - } - } - } - ] + "required": [ + "username", + "user_id" + ] + } + }, + "subdomain": { + "type": "string", + "description": "The subdomain created for this reverse DNS. 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 Reverse DNS." + }, + "legacy": { + "type": "boolean", + "description": "Indicates if this Reverse DNS was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create a new Reverse DNS if you need to update it." + }, + "last_validation_attempt_at": { + "type": "integer", + "description": "A Unix epoch timestamp representing the last time of a validation attempt." + }, + "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 set up with Reverse DNS." } } - }, - "security": [ + } + }, + "required": [ + "id", + "ip", + "rdns", + "users", + "domain", + "valid", + "legacy", + "a_record" + ], + "example": { + "id": 1, + "ip": "192.168.1.1", + "rdns": "o1.email.example.com", + "users": [ { - "Authorization": [] + "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" + } + } + }, + "senderID": { + "title": "Sender ID", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The unique identifier of the sender identity." + }, + "nickname": { + "type": "string", + "description": "A nickname for the sender identity. Not used for sending." + }, + "from": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is where the email will appear to originate from for your recipient" + }, + "name": { + "type": "string", + "description": "This is the name appended to the from email field. IE - Your name or company name." + } + }, + "required": [ + "email" + ] + }, + "reply_to": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is the email that your recipient will reply to." + }, + "name": { + "type": "string", + "description": "This is the name appended to the reply to email field. IE - Your name or company name." + } + } + }, + "address": { + "type": "string", + "description": "The physical address of the sender identity." + }, + "address_2": { + "type": "string", + "description": "Additional sender identity address information." + }, + "city": { + "type": "string", + "description": "The city of the sender identity." + }, + "state": { + "type": "string", + "description": "The state of the sender identity." + }, + "zip": { + "type": "string", + "description": "The zipcode of the sender identity." + }, + "country": { + "type": "string", + "description": "The country of the sender identity." + }, + "verified": { + "type": "boolean", + "description": "If the sender identity is verified or not. Only verified sender identities can be used to send email." + }, + "updated_at": { + "type": "integer", + "description": "The time the sender identity was last updated." + }, + "created_at": { + "type": "integer", + "description": "The time the sender identity was created." + }, + "locked": { + "type": "boolean", + "description": "A sender identity is locked when it is associated to a campaign in the Draft, Scheduled, or In Progress status. You cannot update or delete a locked sender identity." + } + }, + "required": [ + "nickname", + "address", + "city", + "country" + ], + "example": { + "id": 1, + "nickname": "My Sender ID", + "from": { + "email": "from@example.com", + "name": "Example INC" + }, + "reply_to": { + "email": "replyto@example.com", + "name": "Example INC" + }, + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "state": "Colorado", + "zip": "80202", + "country": "United States", + "verified": true, + "updated_at": 1449872165, + "created_at": 1449872165, + "locked": false + } + }, + "global:empty_request": { + "title": "Global: Request Empty Body", + "type": "null" + }, + "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" + ] + } }, - "post": { - "operationId": "POST_whitelabel-domains", - "summary": "Create a domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { + "example": { + "name": "first_name", + "type": "text" + } + }, + "domain_authentication:domain_spf": { + "title": "Domain Authentication", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the authenticated domain." + }, + "domain": { + "type": "string", + "description": "The domain authenticated." + }, + "subdomain": { + "type": "string", + "description": "The subdomain that was used to create this authenticated domain." + }, + "username": { + "type": "string", + "description": "The username of the account that this authenticated domain is associated with." + }, + "user_id": { + "type": "integer", + "description": "The user_id of the account that this authenticated domain is associated with." + }, + "ips": { + "type": "array", + "description": "The IP addresses that are included in the SPF record for this authenticated domain.", + "items": {} + }, + "custom_spf": { + "type": "boolean", + "description": "Indicates if this authenticated domain uses custom SPF." + }, + "default": { + "type": "boolean", + "description": "Indicates if this is the default domain." + }, + "legacy": { + "type": "boolean", + "description": "Indicates if this authenticated domain was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create a new authenticated domain if you need to update it." + }, + "automatic_security": { + "type": "boolean", + "description": "Indicates if this authenticated domain uses automated security." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid authenticated domain ." + }, + "dns": { + "type": "object", + "description": "The DNS records for this authenticated domain.", + "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": { - "domain": { + "host": { "type": "string", - "description": "Domain being whitelabeled." + "description": "The domain sending the messages." }, - "subdomain": { + "type": { "type": "string", - "description": "The subdomain to use for this domain whitelabel." + "description": "They type of DNS record." }, - "username": { + "data": { "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" - } + "description": "The mail server responsible for accepting messages from the sending domain." }, - "custom_spf": { + "valid": { "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." + "description": "Indicates if this is a valid DNS record." + } + } + }, + "subdomain_spf": { + "type": "object", + "description": "The SPF record for the subdomain used to create this authenticated domain.", + "required": [ + "host", + "type", + "data", + "valid" + ], + "properties": { + "host": { + "type": "string", + "description": "The domain that this SPF record will be used to authenticate." }, - "default": { - "type": "boolean", - "description": "Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain." + "type": { + "type": "string", + "description": "The type of data in the SPF record." }, - "automatic_security": { + "data": { + "type": "string", + "description": "The SPF record." + }, + "valid": { "type": "boolean", - "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation." + "description": "Indicates if this is a valid SPF record." } - }, + } + }, + "domain_spf": { + "type": "object", + "description": "The SPF record for the root domain.", "required": [ - "domain", - "subdomain" + "host", + "type", + "data", + "valid" ], - "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 + "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." + } } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" - } + "dkim": { + "type": "object", + "description": "The DKIM record for messages sent using this authenticated domain.", + "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", + "username", + "user_id", + "ips", + "custom_spf", + "default", + "legacy", + "automatic_security", + "valid", + "dns" + ] + }, + "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." }, - "security": [ - { - "Authorization": [] - } - ] - } - }, - "/whitelabel/domains/{domain_id}": { - "parameters": [ - { - "name": "domain_id", - "in": "path", - "required": true, - "type": "string" + "email": { + "type": "string", + "description": "The email address to contact this subuser.", + "format": "email" } + }, + "required": [ + "disabled", + "id", + "username", + "email" ], - "get": { - "operationId": "GET_whitelabel-domains-domain_id", - "summary": "Retrieve a domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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)", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel::domain" - } - } + "example": { + "disabled": false, + "email": "example@example.com", + "id": 1234, + "username": "example_subuser" + } + }, + "mail_settings_address_whitelabel": { + "title": "Mail Settings: Address Whitelabel", + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if you have an email address whitelist enabled. " }, - "security": [ - { - "Authorization": [] + "list": { + "type": "array", + "description": "All email addresses that are currently on the whitelist.", + "items": { + "type": "string" } - ] + } }, - "patch": { - "operationId": "PATCH_whitelabel-domains-domain_id", - "summary": "Update a domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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)", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { + "example": { + "enabled": true, + "list": [ + "email1@example.com", + "example.com" + ] + } + }, + "link_branding_200_response": { + "title": "Link Branding 200 Response", + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The ID of the branded link." + }, + "domain": { + "type": "string", + "description": "The root domain of the branded link." + }, + "subdomain": { + "type": "string", + "description": "The subdomain used to generate the DNS records for this link branding. This subdomain must be different from the subdomain used for your authenticated domain." + }, + "username": { + "type": "string", + "description": "The username of the account that this link branding is associated with." + }, + "user_id": { + "type": "integer", + "description": "The ID of the user that this link branding is associated with." + }, + "default": { + "type": "boolean", + "description": "Indicates if this is the default link branding.", + "enum": [ + true, + false + ] + }, + "valid": { + "type": "boolean", + "description": "Indicates if this link branding is valid.", + "enum": [ + true, + false + ] + }, + "legacy": { + "type": "boolean", + "description": "Indicates if this link branding was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create new link branding if you need to update it.", + "enum": [ + true, + false + ] + }, + "dns": { + "type": "object", + "description": "The DNS records generated for this link branding.", + "required": [ + "domain_cname" + ], + "properties": { + "domain_cname": { "type": "object", + "description": "The DNS record generated to point to your link branding subdomain.", + "required": [ + "valid", + "type", + "host", + "data" + ], "properties": { - "default": { + "valid": { "type": "boolean", - "default": false, - "description": "Indicates whether this domain whitelabel should be considered the default." + "description": "Indicates if the DNS record is valid.", + "enum": [ + true, + false + ] }, - "custom_spf": { - "type": "boolean", - "default": false, - "description": "Indicates whether to generate a custom SPF record for manual security." + "type": { + "type": "string", + "description": "The type of DNS record that was generated.", + "enum": [ + "cname", + "txt", + "mx" + ] + }, + "host": { + "type": "string", + "description": "The domain that this link branding will use for the links in your email." + }, + "data": { + "type": "string", + "description": "The domain that the DNS record points to." } - }, - "example": { - "default": false, - "custom_spf": true } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "title": "Update a Domain response", + }, + "owner_cname": { "type": "object", + "description": "The DNS record generated to verify who created the link branding.", "properties": { - "default false": { - "description": "Inidcates whether this domain whitelabel should be considered the default. Defaults to false.", - "type": "boolean" + "valid": { + "type": "boolean", + "description": "Indicates if the DNS record is valid.", + "enum": [ + true, + false + ] }, - "custom_spf false": { - "description": "Indicates whether to generate a custom SPF record for manual security. Defaults to false.", - "type": "boolean" + "type": { + "type": "string", + "description": "The type of DNS record generated.", + "enum": [ + "cname", + "txt", + "mx" + ] + }, + "host": { + "type": "string", + "description": "Used to verify the link branding. The subdomain of this domain is the ID of the user who created the link branding." + }, + "data": { + "type": "string", + "description": "The domain that the DNS record points to." } - } + }, + "required": [ + "valid", + "host", + "data" + ] } } - }, - "security": [ - { - "Authorization": [] - } - ] + } }, - "delete": { - "operationId": "DELETE_whitelabel-domains-domain_id", - "summary": "Delete a domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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)", - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - } + "required": [ + "id", + "domain", + "username", + "user_id", + "default", + "valid", + "legacy", + "dns" + ] + }, + "from_email_object": { + "title": "From Email Object", + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email", + "description": "The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account." }, - "security": [ - { - "Authorization": [] - } - ] + "name": { + "type": "string", + "description": "A name or title associated with the sending email address." + } + }, + "required": [ + "email" + ], + "example": { + "email": "jane_doe@example.com", + "name": "Jane Doe" } }, - "/whitelabel/domains/default": { - "get": { - "operationId": "GET_whitelabel-domains-default", - "summary": "Get the default domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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. |", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" + "api_key_name_id_scopes": { + "title": "API Key Name, ID, and Scopes", + "allOf": [ + { + "type": "object", + "properties": { + "scopes": { + "type": "array", + "description": "The permissions this API Key has access to.", + "items": { + "type": "string" + } } } }, - "security": [ - { - "Authorization": [] - } + { + "$ref": "#/definitions/api_key_name_id" + } + ], + "example": { + "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", + "name": "Mail Send", + "scopes": [ + "mail.send", + "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", + "sender_verification_eligible", + "sender_verification_legacy", + "2fa_required" ] } }, - "/whitelabel/domains/{id}/ips": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "string" + "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" ], - "post": { - "operationId": "POST_whitelabel-domains-id-ips", - "summary": "Add an IP to a domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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 |", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ + "example": { + "name": "Last Name Miller", + "list_id": 4, + "conditions": [ { - "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" - ], - "example": { - "ip": "192.168.0.1" - } - } + "field": "last_name", + "value": "Miller", + "operator": "eq", + "and_or": "" }, { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "field": "last_clicked", + "value": "01/02/2015", + "operator": "gt", + "and_or": "and" + }, + { + "field": "clicks.campaign_identifier", + "value": "513", + "operator": "eq", + "and_or": "or" } ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/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 - } - } - } - } - } + "recipient_count": 1234 + } + }, + "api_key_name_id": { + "title": "API Key Name and ID", + "type": "object", + "properties": { + "api_key_id": { + "type": "string", + "description": "The ID of your API Key. " }, - "security": [ - { - "Authorization": [] - } - ] + "name": { + "type": "string", + "description": "The name of your API Key." + } + }, + "example": { + "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", + "name": "Mail Send" } }, - "/whitelabel/domains/{id}/ips/{ip}": { - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "type": "string" + "advanced_stats_opens": { + "title": "Stats: Advanced Stats with Opens", + "type": "object", + "description": "The individual events and their stats.", + "properties": { + "opens": { + "type": "integer", + "description": "The total number of times your emails were opened by recipients." }, - { - "name": "ip", - "in": "path", - "required": true, - "type": "string" + "unique_opens": { + "type": "integer", + "description": "The number of unique recipients who opened your emails." } - ], - "delete": { - "operationId": "DELETE_whitelabel-domains-id-ips-ip", - "summary": "Remove an IP from a domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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. |", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } + } + }, + "mail_settings_template": { + "title": "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." + } + }, + "example": { + "enabled": false, + "html_content": "

<% body %>Example

\n" + } + }, + "ip_warmup_response": { + "title": "IP Warmup: IP", + "type": "array", + "items": { + "type": "object", + "properties": { + "ip": { + "type": "string", + "description": "The IP address." }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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 - } - } - } - } + "start_date": { + "type": "integer", + "description": "A Unix timestamp indicating when the IP address entered warmup mode." } }, - "security": [ - { - "Authorization": [] - } + "required": [ + "ip", + "start_date" ] - } - }, - "/whitelabel/domains/{id}/validate": { - "parameters": [ + }, + "example": [ { - "name": "id", - "in": "path", - "required": true, - "type": "string" + "ip": "0.0.0.0", + "start_date": 1409616000 + } + ] + }, + "monitor": { + "title": "Create monitor settings request", + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address to which Sendgrid should send emails for monitoring.", + "format": "email" + }, + "frequency": { + "type": "number", + "description": "The frequency at which to forward monitoring emails. An email will be sent when your subuser sends this many (e.g., 1,000) emails." } + }, + "required": [ + "email", + "frequency" ], - "post": { - "operationId": "POST_whitelabel-domains-id-validate", - "summary": "Validate a domain whitelabel.", - "tags": [ - "Whitelabel - Domains" - ], - "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. |", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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_results": { - "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_results": { - "mail_cname": { - "valid": false, - "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\"." - }, - "dkim1": { - "valid": true, - "reason": null - }, - "dkim2": { - "valid": true, - "reason": null - }, - "spf": { - "valid": true, - "reason": null - } - } - } - } - }, - "500": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message explaining the reason for the error." - } - }, - "required": [ - "message" - ] - } - } + "example": { + "email": "example@example.com", + "frequency": 50000 + } + }, + "global_error_response_schema": { + "title": "Global Error Response Schema", + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "the error message" + }, + "field": { + "type": [ + "string", + "null" + ], + "description": "the field that generated the error" + }, + "help": { + "type": "object", + "description": "helper text or docs for troubleshooting" } }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting TXT" - } - ] - } - } + "required": [ + "message" + ] } }, - "security": [ + "id": { + "type": "string" + } + }, + "example": { + "errors": [ { - "Authorization": [] + "field": "field_name", + "message": "error message" } ] } }, - "/whitelabel/domains/subuser": { - "get": { - "operationId": "GET_whitelabel-domains-subuser", - "summary": "List the domain whitelabel associated with the given user.", - "tags": [ - "Whitelabel - Domains" - ], - "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. |", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/whitelabel:domain_spf" + "advanced_stats_mailbox_provider": { + "title": "Stats: Advanced Stats for Mailbox Provider", + "description": "The individual events and their stats.", + "allOf": [ + { + "$ref": "#/definitions/advanced_stats_clicks_opens" + }, + { + "type": "object", + "description": "The individual events and their stats.", + "properties": { + "blocks": { + "type": "integer", + "description": "The number of emails that were not allowed to be delivered by ISPs." }, - "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 - } - } - } + "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." + }, + "requests": { + "type": "integer", + "description": "The number of emails that were requested to be delivered." + }, + "processed": { + "type": "integer", + "description": "Requests from your website, application, or mail client via SMTP Relay or the Web API that SendGrid processed." + }, + "spam_reports": { + "type": "integer", + "description": "The number of recipients who marked your email as spam." + } + } + } + ] + }, + "contactdb_custom_field_with_id": { + "title": "ContactDB Custom field schema with ID.", + "allOf": [ + { + "$ref": "#/definitions/contactdb_custom_field" + }, + { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The ID of the custom field." } } + } + ] + }, + "ip_pool": { + "title": "IP Pools: Pool", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the IP pool.", + "maxLength": 64 + } + }, + "required": [ + "name" + ] + }, + "google_analytics_settings": { + "title": "Settings: Google Analytics", + "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." + } + }, + "example": { + "enabled": true, + "utm_source": "sendgrid.com", + "utm_medium": "email", + "utm_term": "", + "utm_content": "", + "utm_campaign": "website" + } + }, + "event-webhook-response": { + "title": "Webhooks: Event Webhook Response", + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the event webhook is enabled." + }, + "url": { + "type": "string", + "description": "The URL that you want the event webhook to POST to." + }, + "group_resubscribe": { + "type": "boolean", + "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." + }, + "delivered": { + "type": "boolean", + "description": "Message has been successfully delivered to the receiving server." + }, + "group_unsubscribe": { + "type": "boolean", + "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." + }, + "spam_report": { + "type": "boolean", + "description": "Recipient marked a message as spam." + }, + "bounce": { + "type": "boolean", + "description": "Receiving server could not or would not accept message." + }, + "deferred": { + "type": "boolean", + "description": "Recipient's email server temporarily rejected message." + }, + "unsubscribe": { + "type": "boolean", + "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." + }, + "processed": { + "type": "boolean", + "description": "Message has been received and is ready to be delivered." + }, + "open": { + "type": "boolean", + "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." + }, + "click": { + "type": "boolean", + "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." + }, + "dropped": { + "type": "boolean", + "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" + }, + "oauth_client_id": { + "type": "string", + "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token." + }, + "oauth_token_url": { + "type": "string", + "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider." + } + }, + "required": [ + "enabled", + "url", + "group_resubscribe", + "delivered", + "group_unsubscribe", + "spam_report", + "bounce", + "deferred", + "unsubscribe", + "processed", + "open", + "click", + "dropped" + ] + }, + "user_profile": { + "title": "User: Profile", + "type": "object", + "properties": { + "address": { + "type": "string", + "description": "The street address for this user profile." + }, + "address2": { + "type": "string", + "description": "An optional second line for the street address of this user profile." + }, + "city": { + "type": "string", + "description": "The city for the user profile." + }, + "company": { + "type": "string", + "description": "That company that this user profile is associated with." }, - "security": [ - { - "Authorization": [] - } - ] - }, - "delete": { - "operationId": "DELETE_whitelabel-domains-subuser", - "summary": "Disassociate a domain whitelabel from a given user.", - "tags": [ - "Whitelabel - Domains" - ], - "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. |", - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - } + "country": { + "type": "string", + "description": "Th country of this user profile." }, - "security": [ - { - "Authorization": [] - } - ] + "first_name": { + "type": "string", + "description": "The first name of the user." + }, + "last_name": { + "type": "string", + "description": "The last name of the user." + }, + "phone": { + "type": "string", + "description": "The phone number for the user." + }, + "state": { + "type": "string", + "description": "The state for this user." + }, + "website": { + "type": "string", + "description": "The website associated with this user." + }, + "zip": { + "type": "string", + "description": "The zip code for this user." + } + }, + "example": { + "address": "1451 Larimer Street, 3rd floor", + "address2": "", + "city": "Denver, CO", + "company": "SendGrid", + "country": "US", + "first_name": "Matthew", + "last_name": "Bernier", + "phone": "7208788003", + "state": "CO", + "website": "http://sendgrid.com", + "zip": "80202" } }, - "/whitelabel/domains/{domain_id}/subuser": { - "parameters": [ - { - "name": "domain_id", - "in": "path", - "required": true, - "type": "string" + "mail_settings_footer": { + "title": "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." } - ], - "post": { - "operationId": "POST_whitelabel-domains-domain_id-subuser", - "summary": "Associate a domain whitelabel with a given user.", - "tags": [ - "Whitelabel - Domains" - ], - "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. |", - "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" - ], - "example": { - "username": "jane@example.com" - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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 + }, + "example": { + "enabled": true, + "html_content": "Example HTML content", + "plain_content": "Example plain content" + } + }, + "category_stats": { + "title": "Stats: 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." }, - "subdomain_spf": { - "host": "mail.example.com", - "type": "txt", - "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", - "valid": false + "bounce_drops": { + "type": "integer", + "description": "The number of emails that were dropped because of a bounce." }, - "domain_spf": { - "host": "example.com", - "type": "txt", - "data": "v=spf1 include:mail.example.com -all", - "valid": false + "bounces": { + "type": "integer", + "description": "The number of emails that bounced instead of being delivered." }, - "dkim": { - "host": "s1._domainkey.example.com", - "type": "txt", - "data": "k=rsa; t=s; p=publicKey", - "valid": false + "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" + ] } - }, - "security": [ + } + }, + "required": [ + "date" + ], + "example": { + "date": "2015-01-01", + "stats": [ { - "Authorization": [] + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "cat1", + "type": "category" + }, + { + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 0, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 0, + "processed": 0, + "requests": 0, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "cat2", + "type": "category" } ] } }, - "/whitelabel/ips": { - "get": { - "operationId": "GET_whitelabel-ips", - "summary": "Retrieve all IP whitelabels", - "tags": [ - "Whitelabel - IPs" - ], - "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).", - "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" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" - } - } - ] + "parse-setting": { + "title": "Parse Setting", + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL." + }, + "hostname": { + "type": "string", + "description": "A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, `parse.yourdomain.com`." + }, + "spam_check": { + "type": "boolean", + "description": "Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain." + }, + "send_raw": { + "type": "boolean", + "description": "Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to `true`, SendGrid will send a JSON payload of the content of your email." + } + }, + "example": { + "url": "http://email.myhostname.com", + "hostname": "myhostname.com", + "spam_check": false, + "send_raw": true + } + }, + "transactional_template": { + "title": "Transactional Templates: Template", + "allOf": [ + { + "$ref": "#/definitions/transactional-templates-template-lean" + }, + { + "type": "object", + "properties": { + "warning": { + "$ref": "#/definitions/transactional-template-warning" } } + } + ], + "example": { + "id": "33feeff2-5069-43fe-8853-428651e5be79", + "name": "example_name", + "updated_at ": "2021-04-28 13:12:46", + "warning": { + "message": "Sample warning message" + }, + "generation": "legacy" + } + }, + "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. Must be unique against all other list and segment names." + }, + "recipient_count": { + "type": "integer", + "description": "The count of recipients currently in the list." + } + }, + "required": [ + "id", + "name", + "recipient_count" + ], + "example": { + "id": 1, + "name": "listname", + "recipient_count": 0 + } + }, + "suppression_group": { + "title": "Suppressions: 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" }, - "security": [ - { - "Authorization": [] - } - ] + "is_default": { + "type": "boolean", + "default": false, + "description": "Indicates if this is the default suppression group." + }, + "unsubscribes": { + "type": "integer", + "description": "The unsubscribes associated with this group." + } }, - "post": { - "operationId": "POST_whitelabel-ips", - "summary": "Create an IP whitelabel", - "tags": [ - "Whitelabel - IPs" - ], - "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).", - "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" - ], - "example": { - "ip": "192.168.1.1", - "subdomain": "email", - "domain": "example.com" + "required": [ + "id", + "name", + "description" + ] + }, + "mail_settings_bounce_purge": { + "title": "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." + } + }, + "example": { + "enabled": false, + "soft_bounces": 1234, + "hard_bounces": null + } + }, + "transactional_template_version_output": { + "title": "Transactional Templates: Version Output", + "allOf": [ + { + "type": "object", + "properties": { + "warnings": { + "type": "array", + "items": { + "$ref": "#/definitions/transactional-template-warning" } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } - ], - "responses": { - "201": { - "description": "", - "schema": { - "$ref": "#/definitions/ip_whitelabel" + }, + { + "$ref": "#/definitions/transactional_template_version_create" + }, + { + "$ref": "#/definitions/transactional-templates-version-output-lean" + } + ] + }, + "credentials": { + "title": "Credentials", + "type": "object", + "properties": { + "permissions": { + "type": "object", + "properties": { + "api": { + "type": "string" }, - "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" - } - } + "mail": { + "type": "string" + }, + "web": { + "type": "string" } } }, - "security": [ - { - "Authorization": [] - } - ] + "username": { + "type": "string" + } + }, + "example": { + "address": "1234 example street", + "address2": null, + "city": "Denver", + "company": "Company name", + "country": "US", + "email": "example@example.com", + "first_name": "Example", + "last_name": "User", + "phone": "(555) 555-5555", + "state": "CO", + "zip": "55555" } }, - "/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" + "global:id": { + "title": "Global: ID", + "type": "integer" + }, + "mail_settings_forward_spam": { + "title": "Mail Settings: Forward Spam", + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "The email address where you would like the spam reports to be forwarded." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if the Forward Spam setting is enabled." } - ], - "get": { - "operationId": "GET_whitelabel-ips-id", - "summary": "Retrieve an IP whitelabel", - "tags": [ - "Whitelabel - IPs" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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." - } - ] - } - } + }, + "example": { + "email": "", + "enabled": true + } + }, + "campaign_request": { + "title": "Campaigns 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" } }, - "security": [ - { - "Authorization": [] + "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. Segments are limited to 10 segment 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." + }, + "editor": { + "type": "string", + "enum": [ + "code", + "design" + ], + "description": "The editor used in the UI." + } }, - "delete": { - "operationId": "DELETE_whitelabel-ips-id", - "summary": "Delete an IP whitelabel", - "tags": [ - "Whitelabel - IPs" + "required": [ + "title" + ], + "example": { + "id": 986724, + "title": "May Newsletter", + "subject": "New Products for Summer!", + "sender_id": 124451, + "list_ids": [ + 110, + 124 ], - "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).", - "produces": [ - "application/json" + "segment_ids": [ + 110 ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } + "categories": [ + "summer line" ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - }, - "404": { - "description": "", - "schema": { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "The errors preventing the IP whitelabel from being deleted.", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string", - "description": "A message explaining why the IP whitelabel could not be deleted." - } - } + "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" + } + }, + "subuser_stats": { + "title": "subuser_stats", + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "The date the statistics were gathered." + }, + "stats": { + "type": "array", + "description": "The list of statistics.", + "items": { + "type": "object", + "properties": { + "first_name": { + "type": "string", + "description": "The first name of the subuser." + }, + "last_name": { + "type": "string", + "description": "The last name of the subuser." + }, + "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." } } - } - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "Whitelabel ip not found." - } - ] + }, + "name": { + "type": "string", + "description": "The username of the subuser." + }, + "type": { + "type": "string", + "description": "The type of account." } } } - }, - "security": [ + } + }, + "example": { + "date": "2016-02-01", + "stats": [ { - "Authorization": [] + "first_name": "John", + "last_name": "Doe", + "metrics": { + "blocks": 0, + "bounce_drops": 0, + "bounces": 0, + "clicks": 5, + "deferred": 0, + "delivered": 0, + "invalid_emails": 0, + "opens": 10, + "processed": 10, + "requests": 10, + "spam_report_drops": 0, + "spam_reports": 0, + "unique_clicks": 0, + "unique_opens": 0, + "unsubscribe_drops": 0, + "unsubscribes": 0 + }, + "name": "user1", + "type": "subuser" } ] } }, - "/whitelabel/ips/{id}/validate": { - "parameters": [ + "user_scheduled_send_status": { + "title": "User Scheduled Send status", + "allOf": [ { - "name": "id", - "in": "path", - "required": true, - "type": "integer" + "$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" + ] } ], - "post": { - "operationId": "POST_whitelabel-ips-id-validate", - "summary": "Validate an IP whitelabel", - "tags": [ - "Whitelabel - IPs" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" + "example": { + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", + "status": "pause" + } + }, + "advanced_stats_clicks_opens": { + "title": "Stats: Advanced Stats with Clicks and Opens", + "description": "The individual events and their stats.", + "allOf": [ + { + "$ref": "#/definitions/advanced_stats_clicks" + }, + { + "$ref": "#/definitions/advanced_stats_opens" + } + ] + }, + "contactdb_segments_with_id": { + "title": "ContactDB:: Segments with ID", + "allOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The ID of the segment." } }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" + ] + }, + { + "$ref": "#/definitions/contactdb_segments" + } + ] + }, + "advanced_stats_clicks": { + "title": "Stats: Advanced Stats with Clicks", + "type": "object", + "description": "The individual events and their stats.", + "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." + } + } + }, + "contactdb_recipient": { + "title": "ContactDB: Recipient", + "type": "object", + "properties": { + "recipients": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of this recipient." }, - "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" - ] - } - } + "created_at": { + "type": "number", + "description": "The time this record was created in your contactdb, in unixtime." }, - "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" - ] - } + "custom_fields": { + "type": "array", + "description": "The custom fields assigned to this recipient and their values.", + "items": { + "$ref": "#/definitions/contactdb_custom_field_with_id_value" } }, - "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting rDNS" - } - ] + "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" + ] } + } + } + }, + "mail_settings_patch": { + "title": "Mail Settings: Patch", + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the mail setting is enabled." }, - "security": [ - { - "Authorization": [] - } - ] + "email": { + "type": "string", + "description": "The email address of the recipient." + } + }, + "example": { + "enabled": true, + "email": "email@example.com" } }, - "/whitelabel/links": { - "get": { - "operationId": "GET_whitelabel-links", - "summary": "Retrieve all link whitelabels", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Limits the number of results returned per page.", - "type": "integer" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" - } - } - } - ] + "mail_settings_forward_bounce": { + "title": "Mail Settings: Forward Bounce", + "type": "object", + "properties": { + "email": { + "type": [ + "string", + "null" + ], + "description": "The email address that you would like your bounce reports forwarded to." + }, + "enabled": { + "type": "boolean", + "description": "Indicates if the bounce forwarding mail setting is enabled." + } + }, + "example": { + "enabled": false, + "email": null + } + }, + "mail_batch_id": { + "title": "Mail Batch ID", + "type": "object", + "properties": { + "batch_id": { + "type": "string", + "pattern": "^[a-zA-Z0-9\\-\\_]" + } + }, + "required": [ + "batch_id" + ], + "example": { + "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" + } + }, + "subuser_post": { + "title": "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" + ], + "example": { + "username": "example_subuser", + "user_id": 1234, + "email": "example@example.com", + "signup_session_token": "", + "authorization_token": "", + "credit_allocation": { + "type": "unlimited" + } + } + }, + "contactdb_recipient_count": { + "title": "ContactDB: Recipient Count", + "type": "object", + "properties": { + "recipient_count": { + "type": "number", + "description": "The count of recipients." + } + }, + "required": [ + "recipient_count" + ], + "example": { + "recipient_count": 1234 + } + }, + "authentication::domain": { + "title": "Domain Authentication - Mandatory Subdomain", + "type": "object", + "properties": { + "id": { + "type": "number", + "description": "The ID of the authenticated domain." + }, + "user_id": { + "type": "number", + "description": "The ID of the user that this domain is associated with." + }, + "subdomain": { + "type": "string", + "description": "The subdomain to use for this authenticated domain." + }, + "domain": { + "type": "string", + "description": "The domain to be authenticated." + }, + "username": { + "type": "string", + "description": "The username that this domain will be associated with." + }, + "ips": { + "type": "array", + "description": "The IPs to be included in the custom SPF record for this authenticated domain.", + "items": { + "type": "string" + } }, - "security": [ - { - "Authorization": [] - } - ] - }, - "post": { - "operationId": "POST_whitelabel-links", - "summary": "Create a Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "Number of domains to return.", - "type": "integer", - "default": 50 - }, - { - "name": "offset", - "in": "query", - "description": "Paging offset.", - "type": "integer", - "default": 0 - }, - { - "name": "body", - "in": "body", - "schema": { + "custom_spf": { + "type": "boolean", + "description": "Indicates whether this authenticated domain uses custom SPF." + }, + "default": { + "type": "boolean", + "description": "Indicates if this is the default authenticated domain." + }, + "legacy": { + "type": "boolean", + "description": "Indicates if this authenticated domain was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create a new authenticated domain if you need to update it." + }, + "automatic_security": { + "type": "boolean", + "description": "Indicates if this authenticated domain uses automated security." + }, + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid authenticated domain." + }, + "dns": { + "type": "object", + "description": "The DNS records 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": { - "domain": { + "valid": { + "type": "boolean", + "description": "Indicates if this is a valid CNAME." + }, + "type": { "type": "string", - "description": "The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address." + "description": "The type of DNS record." }, - "subdomain": { + "host": { "type": "string", - "description": "The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel." + "description": "The domain that this CNAME is created for.", + "format": "hostname" }, - "default": { - "type": "boolean", - "description": "Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.", - "enum": [ - true, - false - ] + "data": { + "type": "string", + "description": "The CNAME record." } - }, - "required": [ - "domain", - "subdomain" - ], - "example": { - "domain": "example.com", - "subdomain": "mail", - "default": true } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" - } + "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." } } - } - } - }, - "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": { - "operationId": "GET_whitelabel-links-id", - "summary": "Retrieve a Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" - } - } - } - } - } - }, - "security": [ - { - "Authorization": [] - } - ] - }, - "patch": { - "operationId": "PATCH_whitelabel-links-id", - "summary": "Update a Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { + "dkim2": { "type": "object", + "description": "A DNS record.", + "required": [ + "valid", + "type", + "host", + "data" + ], "properties": { - "default": { + "valid": { "type": "boolean", - "description": "Indicates if the link whitelabel is set as the default, or fallback, whitelabel.", - "enum": [ - true, - false - ] + "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." } - }, - "example": { - "default": true } } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } - ], - "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" - } - } - } + } + }, + "required": [ + "id", + "user_id", + "subdomain", + "domain", + "username", + "ips", + "custom_spf", + "default", + "legacy", + "automatic_security", + "valid", + "dns" + ] + }, + "contactdb_custom_field_with_id_value": { + "title": "ContactDB Custom field schema.", + "allOf": [ + { + "$ref": "#/definitions/contactdb_custom_field_with_id" + }, + { + "type": "object", + "properties": { + "value": { + "type": [ + "string", + "null" + ], + "description": "The value of this recipient's custom field" } } + } + ] + }, + "transactional_template_version_create": { + "title": "Transactional Templates: Version Create", + "type": "object", + "properties": { + "active": { + "type": "integer", + "description": "Set the version as the active version associated with the template (0 is inactive, 1 is active). 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 + ] }, - "security": [ - { - "Authorization": [] - } - ] + "name": { + "type": "string", + "description": "Name of the transactional template version.", + "maxLength": 100 + }, + "html_content": { + "type": "string", + "description": "The HTML content of the version. Maximum of 1048576 bytes allowed.", + "maxLength": 1048576 + }, + "plain_content": { + "type": "string", + "description": "Text/plain content of the transactional template version. Maximum of 1048576 bytes allowed.", + "maxLength": 1048576, + "default": "" + }, + "generate_plain_content": { + "type": "boolean", + "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", + "default": true + }, + "subject": { + "type": "string", + "description": "Subject of the new transactional template version.", + "maxLength": 255 + }, + "editor": { + "type": "string", + "enum": [ + "code", + "design" + ], + "description": "The editor used in the UI." + }, + "test_data": { + "type": "string", + "description": "For dynamic templates only, the mock json data that will be used for template preview and test sends." + } }, - "delete": { - "operationId": "DELETE_whitelabel-links-id", - "summary": "Delete a Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } - } + "required": [ + "name", + "subject" + ], + "example": { + "template_id": "Excepteur Ut qui", + "active": 1, + "name": "pariatur non incididunt commodo", + "html_content": "dolor", + "generate_plain_content": false, + "subject": "aliquip nulla Ut", + "editor": "design", + "plain_content": "labore dolore" + } + }, + "transactional-templates-version-output-lean": { + "title": "Transactional Templates: Version Output Lean", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "ID of the transactional template version.", + "format": "uuid" }, - "security": [ - { - "Authorization": [] + "template_id": { + "type": "string", + "description": "ID of the transactional template." + }, + "active": { + "type": "integer", + "description": "Set the 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 transactional template version.", + "maxLength": 100 + }, + "subject": { + "type": "string", + "description": "Subject of the new transactional template version.", + "maxLength": 255 + }, + "updated_at": { + "type": "string", + "description": "The date and time that this transactional template version was updated." + }, + "generate_plain_content": { + "type": "boolean", + "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", + "default": true + }, + "editor": { + "type": "string", + "enum": [ + "code", + "design" + ], + "description": "The editor used in the UI." + }, + "thumbnail_url": { + "type": "string", + "description": "A Thumbnail preview of the template's html content." + } + } + }, + "transactional-templates-template-lean": { + "title": "Transactional Templates: Template Lean", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the transactional template.", + "minLength": 36, + "maxLength": 36, + "format": "uuid" + }, + "name": { + "type": "string", + "description": "The name for the transactional template.", + "maxLength": 100 + }, + "generation": { + "type": "string", + "description": "Defines the generation of the template.", + "enum": [ + "legacy", + "dynamic" + ] + }, + "updated_at ": { + "type": "string", + "description": "The date and time that this transactional template version was updated.", + "pattern": "^(\\d{4}-\\d{2}-\\d{2}) ((\\d{2}):(\\d{2}):(\\d{2}))$" + }, + "versions": { + "type": "array", + "description": "The different versions of this transactional template.", + "items": { + "$ref": "#/definitions/transactional-templates-version-output-lean" } - ] + } + }, + "required": [ + "id", + "name", + "generation", + "updated_at " + ], + "example": { + "id": "0c314114-a2b7-4523-8cbc-a293d7d19007", + "name": "example_name", + "generation": "legacy", + "updated_at ": "2021-04-28 13:12:46", + "versions": [] } }, - "/whitelabel/links/default": { - "get": { - "operationId": "GET_whitelabel-links-default", - "summary": "Retrieve a Default Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "domain", - "in": "query", - "description": "The domain to match against when finding a corresponding link whitelabel.", + "custom-fields-by-id": { + "title": "custom-fields-by-id", + "type": "object", + "example": { + "w1": "2002-10-02T15:00:00Z", + "w33": 9.5, + "e2": "Coffee is a beverage that puts one to sleep when not drank." + } + }, + "custom-fields-by-name": { + "title": "custom-fields-by-name", + "type": "object", + "example": { + "birthday": "2002-10-02T15:00:00Z", + "shoe_size": 9.5, + "favoriteQuote": "Coffee is a beverage that puts one to sleep when not drank." + } + }, + "contact-details": { + "title": "contact-details", + "type": "object", + "properties": { + "address_line_1": { + "type": "string" + }, + "address_line_2": { + "type": "string" + }, + "alternate_emails": { + "type": "array", + "items": { + "type": "string" + } + }, + "city": { + "type": "string" + }, + "country": { + "type": "string" + }, + "email": { + "type": "string" + }, + "first_name": { + "type": "string" + }, + "id": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "postal_code": { + "type": "string" + }, + "state_province_region": { + "type": "string" + }, + "list_ids": { + "type": "array", + "items": { "type": "string" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } - ], - "responses": { - "200": { - "description": "", - "schema": { - "$ref": "#/definitions/link_whitelabel" + }, + "created_at": { + "type": "string", + "description": "The ISO8601 timestamp when the contact was created." + }, + "updated_at": { + "type": "string", + "description": "The ISO8601 timestamp when the contact was updated." + }, + "_metadata": { + "$ref": "#/definitions/selfmetadata" + }, + "custom_fields": { + "$ref": "#/definitions/custom-fields-by-name" + } + }, + "required": [ + "id", + "list_ids", + "created_at", + "updated_at" + ] + }, + "contact-import": { + "title": "contact-import", + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The job ID." + }, + "status": { + "type": "string", + "description": "The job state. Allowed values: `pending`, `completed`, `errored`, or `failed`." + }, + "job_type": { + "type": "string", + "description": "The job type. Allowed values: `upsert`, or `delete`." + }, + "results": { + "type": "object", + "description": "Result map of the import job.", + "properties": { + "requested_count": { + "description": "Requested contact count from the import.", + "type": "number" }, - "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" - } - } - } + "created_count": { + "description": "Created contact count from the import.", + "type": "number" + }, + "updated_count": { + "description": "Updated contact count from the import.", + "type": "number" + }, + "deleted_count": { + "description": "Count of deleted contacts that resulted in error.", + "type": "number" + }, + "errored_count": { + "description": "Count of imported contacts that resulted in error.", + "type": "number" + }, + "errors_url": { + "type": "string", + "description": "The download URL of the file which provides information about any errors." } } }, - "security": [ - { - "Authorization": [] - } - ] + "started_at": { + "description": "The ISO8601 timestamp when the job was created.", + "type": "string" + }, + "finished_at": { + "description": "The ISO8601 timestamp when the job was finished.", + "type": "string" + } } }, - "/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": { - "operationId": "POST_whitelabel-links-id-validate", - "summary": "Validate a Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + "single-contact-request": { + "title": "single contact request", + "type": "object", + "properties": { + "list_ids": { + "type": "array", + "minItems": 0, + "maxItems": 100, + "description": "The contact's list IDs.", + "items": { + "type": "string", + "format": "uuid" } - ], - "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" - ] + }, + "contact": { + "type": "object", + "properties": { + "primary_email": { + "type": "string" }, - "examples": { - "application/json": { - "id": 1, - "valid": true, - "validation_results": { - "domain_cname": { - "valid": false, - "reason": "Expected CNAME to match \"sendgrid.net.\" but found \"example.com.\"." - }, - "owner_cname": { - "valid": true, - "reason": null - } - } - } - } - }, - "500": { - "description": "", - "schema": { + "alternate_emails": { + "type": "string" + }, + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "address_line_1": { + "type": "string" + }, + "address_line_2": { + "type": "string" + }, + "city": { + "type": "string" + }, + "state_province_region": { + "type": "string" + }, + "postal_code": { + "type": "string" + }, + "country": { + "type": "string" + }, + "custom_fields": { "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" - ] - } + "custom_field_name1": { + "type": "string" + }, + "custom_field_name2": { + "type": "string" } - }, - "required": [ - "errors" - ] - }, - "examples": { - "application/json": { - "errors": [ - { - "message": "internal error getting CNAME" - } - ] } } } - }, - "security": [ - { - "Authorization": [] - } - ] + } } }, - "/whitelabel/links/subuser": { - "get": { - "operationId": "GET_whitelabel-links-subuser", - "summary": "Retrieve Associated Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "produces": [ - "application/json" - ], - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of the subuser to retrieve associated link whitelabels for.", - "required": true, + "contact-export": { + "title": "contact-export", + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "ready", + "failure" + ], + "description": "The export job's status. Allowed values: `pending`, `ready`, or `failure`." + }, + "created_at": { + "type": "string", + "description": "The ISO8601 timestamp when the export was begun." + }, + "updated_at": { + "type": "string", + "description": "The ISO8601 timestamp when the export was updated." + }, + "completed_at": { + "type": "string", + "description": "The ISO8601 timestamp when the export was completed." + }, + "expires_at": { + "type": "string", + "description": "The ISO8601 timestamp when the exported file on S3 will expire." + }, + "urls": { + "type": "array", + "description": "One or more download URLs for the contact file if the status is `ready`.", + "items": { "type": "string" - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "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" - } - } - } - } } }, - "security": [ - { - "Authorization": [] - } - ] + "message": { + "type": "string", + "description": "A human readable message if the status is `failure`." + }, + "_metadata": { + "$ref": "#/definitions/metadata" + }, + "contact_count": { + "type": "integer", + "description": "The total number of exported contacts." + } }, - "delete": { - "operationId": "DELETE_whitelabel-links-subuser", - "summary": "Disassociate a Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "parameters": [ - { - "name": "username", - "in": "query", - "description": "The username of the subuser account that you want to disassociate a link whitelabel from.", - "required": true, + "required": [ + "id", + "status", + "created_at", + "updated_at", + "expires_at" + ] + }, + "contact-summary": { + "title": "contact-summary", + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "Primary email address." + }, + "first_name": { + "type": "string" + }, + "id": { + "type": "string", + "description": "Contact UUID." + }, + "last_name": { + "type": "string" + }, + "list_ids": { + "type": "array", + "description": "List UUID linked with this contact.", + "items": { "type": "string" - }, - { - "name": "body", - "in": "body", - "schema": { - "type": "null" - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" - } - ], - "responses": { - "204": { - "description": "", - "schema": { - "type": "object" - } } }, - "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" + "created_at": { + "type": "number", + "description": "Unix Epoch Timestamp." + }, + "updated_at": { + "type": "number", + "description": "Unix Epoch Timestamp." + }, + "_metadata": { + "$ref": "#/definitions/selfmetadata" } - ], - "post": { - "operationId": "POST_whitelabel-links-link_id-subuser", - "summary": "Associate a Link Whitelabel", - "tags": [ - "Whitelabel - Links" - ], - "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).", - "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." - } - }, - "example": { - "username": "jane@example.com" - } - } - }, - { - "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" + }, + "required": [ + "id", + "list_ids", + "created_at", + "updated_at" + ] + }, + "contact-request": { + "title": "contact-request", + "type": "object", + "properties": { + "address_line_1": { + "type": "string", + "description": "The first line of the address.", + "maxLength": 100 + }, + "address_line_2": { + "type": "string", + "description": "An optional second line for the address.", + "maxLength": 100 + }, + "alternate_emails": { + "type": "array", + "description": "Additional emails associated with the contact.", + "minItems": 0, + "maxItems": 5, + "items": { + "type": "string", + "maxLength": 254 } - ], - "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" - } - } - } - } + }, + "city": { + "type": "string", + "description": "The contact's city.", + "maxLength": 60 + }, + "country": { + "type": "string", + "description": "The contact's country. Can be a full name or an abbreviation.", + "maxLength": 50 + }, + "email": { + "type": "string", + "description": "The contact's primary email. This is required to be a valid email.", + "maxLength": 254 + }, + "first_name": { + "type": "string", + "description": "The contact's personal name.", + "maxLength": 50 + }, + "last_name": { + "type": "string", + "description": "The contact's family name.", + "maxLength": 50 + }, + "postal_code": { + "type": "string", + "description": "The contact's ZIP code or other postal code." + }, + "state_province_region": { + "type": "string", + "description": "The contact's state, province, or region.", + "maxLength": 50 + }, + "custom_fields": { + "$ref": "#/definitions/custom-fields-by-id" + } + }, + "required": [ + "email" + ] + }, + "contact-details2": { + "title": "contact-details2", + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 36, + "maxLength": 36, + "format": "uuid" + }, + "first_name": { + "type": "string" + }, + "last_name": { + "type": "string" + }, + "unique_name": { + "type": "string" + }, + "email": { + "type": "string", + "format": "email" + }, + "alternate_emails": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string", + "format": "email" } }, - "security": [ - { - "Authorization": [] + "address_line_1": { + "type": "string" + }, + "address_line_2": { + "type": "string" + }, + "city": { + "type": "string" + }, + "state_province_region": { + "type": "string" + }, + "country": { + "type": "string" + }, + "postal_code": { + "type": "string" + }, + "phone_number": { + "type": "string" + }, + "whatsapp": { + "type": "string" + }, + "line": { + "type": "string" + }, + "facebook": { + "type": "string" + }, + "list_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" } - ] + }, + "segment_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "custom_fields": { + "type": "object" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + }, + "_metadata": { + "$ref": "#/definitions/selfmetadata" + } + }, + "required": [ + "id", + "list_ids", + "created_at", + "updated_at" + ] + }, + "selfmetadata": { + "title": "selfMetadata", + "type": "object", + "properties": { + "self": { + "type": "string", + "description": "A link to this object." + } } - } - }, - "parameters": { - "trait:authorizationHeader:Authorization": { - "name": "Authorization", - "in": "header", - "required": true, - "type": "string", - "default": "Bearer <>" }, - "trait:onBehalfOfSubuser:on-behalf-of": { - "name": "on-behalf-of", - "in": "header", - "type": "string", - "default": "subuser_" - } - }, - "definitions": { - "mail_settings_spam_check": { - "title": "Mail Settings: Spam Check", + "error": { + "title": "error", "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if your Spam Checker mail setting is enabled." + "message": { + "type": "string" }, - "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 + "field": { + "type": "string" }, - "url": { - "type": "string", - "description": "The inbound parse URL where you would like the spam messages to be sent to." + "error_id": { + "type": "string" + }, + "parameter": { + "type": "string" } }, "required": [ - "enabled" - ], - "example": { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } + "message" + ] }, - "suppression_group_unsubscribes": { - "title": "Suppressions: Suppression Group with Unsubscribes", - "allOf": [ - { - "$ref": "#/definitions/suppression_group" + "link": { + "title": "Link", + "type": "object", + "properties": { + "rel": { + "type": "string" }, - { - "properties": { - "unsubscribes": { - "type": "integer", - "description": "The unsubscribes associated with this group." - } - }, - "required": [ - "unsubscribes" - ] + "href": { + "type": "string" } - ], - "type": "object" + } }, - "partner_settings_new_relic": { - "title": "Partner Settings: New Relic", + "metadata": { + "title": "metadata", "type": "object", "properties": { - "enable_subuser_statistics": { - "type": "boolean", - "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." + "prev": { + "type": "string", + "format": "uri", + "description": "The URL of the previous page of results. If this field isn't present, you're at the start of the list." }, - "enabled": { - "type": "boolean", - "description": "Indicates if this setting is enabled. " + "self": { + "type": "string", + "format": "uri", + "description": "The URL of the current page of results." }, - "license_key": { + "next": { "type": "string", - "description": "The license key provided with your New Relic account." + "format": "uri", + "description": "The URL of the next page of results. If this field isn't present, you're at the end of the list." + }, + "count": { + "type": "number", + "description": "The number of items in the entire list, i.e., across all pages." + } + } + }, + "webhook": { + "title": "webhook", + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "The URL to invoke in the webhook" + }, + "nonce": { + "type": "string", + "description": "The one time nonce to use when \"signature\" is \"hmac-sha1\"", + "minLength": 8, + "maxLength": 32 } }, "required": [ - "enabled", - "license_key" + "url", + "nonce" ] }, - "subscription_tracking_settings": { - "title": "Settings: Subscription Tracking", + "list": { + "title": "list", "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if subscription tracking is enabled." + "id": { + "type": "string", + "description": "The generated ID for your list.", + "minLength": 36, + "maxLength": 36, + "format": "uuid" }, - "html_content": { + "name": { "type": "string", - "description": "The information and HTML for your unsubscribe link. " + "description": "The name you gave your list." }, - "landing": { + "contact_count": { + "type": "integer", + "description": "The number of contacts currently stored on the list." + }, + "_metadata": { + "$ref": "#/definitions/selfmetadata" + } + } + }, + "reserved_field_definitions_response": { + "title": "reserved_field_definitions_response", + "type": "object", + "properties": { + "name": { "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." + "minLength": 1, + "maxLength": 100 }, - "plain_content": { + "field_type": { "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." + "enum": [ + "Text", + "Number", + "Date" + ] }, - "replace": { + "read_only": { + "type": "boolean", + "default": false, + "description": "When `true` this means API consumers are unable to set the value of this field on contacts." + } + }, + "required": [ + "name", + "field_type" + ], + "example": { + "id": "_rf20_T", + "name": "automation_id", + "field_type": "Text", + "read_only": true + } + }, + "custom_field_definitions_response": { + "title": "custom_field_definitions_response", + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { "type": "string", - "description": "Your custom defined replacement tag for your templates. Use this tag to place your unsubscribe content anywhere in your emailtemplate." + "minLength": 1, + "maxLength": 100 }, - "url": { + "field_type": { "type": "string", - "description": "The URL where you would like your users sent to unsubscribe." + "enum": [ + "Text", + "Number", + "Date" + ] } + }, + "required": [ + "id", + "name", + "field_type" + ], + "example": { + "id": "a1_D", + "name": "custom_field_name", + "field_type": "Date" } }, - "campaign_response": { - "title": "Campaigns Response", - "allOf": [ - { - "$ref": "#/definitions/campaign_request" + "segment_write": { + "title": "segment_write", + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 }, - { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status of your campaign." - }, - "id": { - "type": "integer" - } - }, - "required": [ - "status" - ] + "query_dsl": { + "type": "string", + "description": "Use this field for adding your query string." } + }, + "required": [ + "name", + "query_dsl" ] }, - "contactdb_recipient_response": { - "title": "ContactDB: Recipient response", + "segment_summary": { + "title": "segment_summary", "type": "object", "properties": { - "error_count": { - "type": "number", - "default": 0, - "description": "The number of errors found while adding recipients." + "id": { + "type": "string", + "minLength": 36, + "maxLength": 36, + "format": "uuid" }, - "error_indices": { - "type": "array", - "default": [], - "description": "The indices of the recipient(s) sent that caused the error. ", - "items": { - "type": "number" - } + "contacts_count": { + "type": "integer" + }, + "created_at": { + "type": "string", + "description": "ISO8601 of created timestamp\n", + "format": "date-time" }, - "new_count": { - "type": "number", - "default": 0, - "description": "The count of new recipients added to the contactdb." + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 }, - "persisted_recipients": { - "type": "array", - "default": [], - "description": "The recipient IDs of the recipients that already existed from this request.", - "items": { - "type": "string" - } + "parent_list_id": { + "type": "string", + "minLength": 36, + "maxLength": 36, + "format": "uuid", + "description": "The id of the list if this segment is a child of a list. This implies the query `AND CONTAINS(list_ids, ${parent_list_id})`" }, - "updated_count": { - "type": "number", - "default": 0, - "description": "The recipients who were updated from this request." + "sample_updated_at": { + "type": "string", + "description": "ISO8601 timestamp the sample was last updated", + "format": "date-time" }, - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_indices": { - "type": "array", - "items": { - "type": "number" - } - } - } - } + "updated_at": { + "type": "string", + "description": "ISO8601 timestamp the object was last updated", + "format": "date-time" + }, + "next_sample_update": { + "type": "string", + "description": "ISO8601 string that is equal to `sample_updated_at` plus an internally calculated offset that depends on how often contacts enter or exit segments as the scheduled pipeline updates the samples." } }, "required": [ - "error_count", - "new_count", - "persisted_recipients", - "updated_count" - ], - "example": { - "error_count": 1, - "error_indices": [ - 2 - ], - "new_count": 2, - "persisted_recipients": [ - "YUBh", - "bWlsbGVyQG1pbGxlci50ZXN0" - ], - "updated_count": 0, - "errors": [ - { - "message": "Invalid email.", - "error_indices": [ - 2 - ] - } - ] - } + "id", + "contacts_count", + "created_at", + "sample_updated_at", + "updated_at" + ] }, - "stats": { - "title": "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": { + "segment_query_json": { + "title": "segment_query_json", + "type": "object", + "properties": { + "contacts": { + "type": "object", + "properties": { + "op": { + "type": "string" + }, + "l": { "type": "object", "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." + "op": { + "type": "string" }, - "metrics": { + "l": { "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." + "op": { + "type": "string" }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." + "l": { + "type": "object", + "properties": { + "v": { + "type": "string" + }, + "t": { + "type": "string" + } + } }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." + "r": { + "type": "object", + "properties": { + "v": { + "type": "string" + }, + "t": { + "type": "string" + } + } + } + } + }, + "r": { + "type": "object", + "properties": { + "op": { + "type": "string" }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." + "l": { + "type": "object", + "properties": { + "v": { + "type": "string" + }, + "t": { + "type": "string" + }, + "args": { + "type": "array", + "items": { + "type": "object", + "properties": { + "v": { + "type": "string" + }, + "t": { + "type": "string" + } + } + } + } + } }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." + "r": { + "type": "object", + "properties": { + "v": { + "type": "string" + }, + "t": { + "type": "string" + } + } + } + } + } + } + }, + "r": { + "type": "object", + "properties": { + "op": { + "type": "string" + }, + "l": { + "type": "object", + "properties": { + "v": { + "type": "string" }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." + "t": { + "type": "string" + } + } + }, + "r": { + "type": "object", + "properties": { + "v": { + "type": "array", + "items": { + "type": "string" + } }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." + "t": { + "type": "string" } } } @@ -23565,2563 +34289,3181 @@ } } }, - "contactdb_segments_conditions": { - "title": "ContactDB: Segments: Conditions", + "contact_response": { + "title": "contact_response", "type": "object", "properties": { - "field": { - "type": "string" - }, - "value": { - "type": "string" - }, - "operator": { + "contact_id": { "type": "string", - "enum": [ - "eq", - "ne", - "lt", - "gt", - "contains" - ] + "maxLength": 36, + "pattern": "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}", + "format": "uuid" }, - "and_or": { + "primary_email": { "type": "string", - "enum": [ - "and", - "or", - "" - ] - } - }, - "required": [ - "field", - "value", - "operator" - ] - }, - "suppression_bounce": { - "title": "Suppression: Bounce", - "type": "object", - "properties": { - "created": { - "type": "number", - "description": "The unix timestamp for when the bounce record was created at SendGrid." - }, - "email": { - "type": "string" + "minLength": 3, + "maxLength": 254, + "format": "email" }, - "reason": { - "type": "string", - "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." + "alternate_emails": { + "type": "array", + "uniqueItems": true, + "minItems": 0, + "items": { + "type": "string", + "minLength": 3, + "maxLength": 254, + "format": "email" + } }, - "status": { + "first_name": { "type": "string", - "description": "Enhanced SMTP bounce response" - } - }, - "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" - } - }, - "ip_whitelabel": { - "title": "Whitelabel - IPs", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the IP whitelabel." + "minLength": 1 }, - "ip": { + "last_name": { "type": "string", - "description": "The IP address that this whitelabel was created for." + "minLength": 1 }, - "rdns": { + "address_line_1": { "type": "string", - "description": "The reverse DNS record for the IP address. This points to the IP whitelabel subdomain." + "minLength": 0 }, - "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" - ] - } + "address_line_2": { + "type": "string", + "minLength": 0 }, - "subdomain": { + "city": { "type": "string", - "description": "The subdomain created for this IP whitelabel. This is where the rDNS record points." + "minLength": 0, + "pattern": "^[a-zA-Z\\u0080-\\u024F\\s\\/\\-\\)\\(\\`\\.\\\"\\']+$" }, - "domain": { + "state_province_region": { "type": "string", - "description": "The root, or sending, domain." + "minLength": 0 }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." + "postal_code": { + "type": "integer" }, - "legacy": { - "type": "boolean", - "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." + "country": { + "type": "string", + "minLength": 0 }, - "a_record": { + "list_ids": { + "type": "array", + "uniqueItems": true, + "description": "IDs of all lists the contact is part of.", + "items": { + "type": "string", + "format": "uuid" + } + }, + "custom_fields": { "type": "object", - "required": [ - "valid", - "type", - "host", - "data" - ], + "minProperties": 0, "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the a_record is valid." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { + "custom_field_name1": { "type": "string", - "description": "This is the web address that will be mapped to the IP address." + "minLength": 0 }, - "data": { + "custom_field_name2": { "type": "string", - "description": "The IP address being whitelabeled." + "minLength": 0 } } } }, "required": [ - "id", - "ip", - "rdns", - "users", - "subdomain", - "domain", - "valid", - "legacy", - "a_record" - ], - "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 + "contact_id", + "primary_email", + "alternate_emails", + "first_name", + "last_name", + "address_line_1", + "address_line_2", + "city", + "state_province_region", + "postal_code", + "country", + "custom_fields" + ] + }, + "TNE-senderID": { + "title": "Sender ID Response Body", + "allOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "The unique identifier of the sender." + } + } + }, + { + "$ref": "#/definitions/senders-id-request-body" + }, + { + "type": "object", + "properties": { + "verified": { + "type": "object", + "description": "Only verified sender identities can be used to send email.", + "properties": { + "status": { + "type": "boolean", + "description": "Whether the sender identity has been verified. Only verified sender identities can be used to send email." + }, + "reason": { + "type": [ + "string", + "null" + ], + "description": "The reason for a verification failure, or null if verification succeeeded or has yet to take place." + } + } + }, + "updated_at": { + "type": "integer", + "description": "The time the sender identity was last updated." + }, + "created_at": { + "type": "integer", + "description": "The time the sender identity was created." + }, + "locked": { + "type": "boolean", + "description": "A sender identity is locked when it is associated with a campaign in the Draft, Scheduled, or In Progress state. You can't update or delete a locked sender identity." + } } - ], - "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" } - } + ] }, - "contacts": { - "title": "Contacts", + "api-error": { + "title": "error", "type": "object", "properties": { - "address": { + "message": { "type": "string" }, - "address2": { - "type": "object" - }, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "email": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { + "field": { "type": "string" }, - "zip": { + "error_id": { "type": "string" } + }, + "required": [ + "message", + "field", + "error_id" + ] + }, + "api-errors": { + "title": "errors", + "type": "object", + "properties": { + "errors": { + "type": "array", + "items": { + "$ref": "#/definitions/api-error" + } + } } }, - "senderID": { - "title": "Sender ID", + "_metadata": { + "title": "_metadata", "type": "object", "properties": { - "id": { - "type": "integer", - "description": "The unique identifier of the sender identity." + "prev": { + "type": "string", + "format": "uri" }, - "nickname": { + "self": { "type": "string", - "description": "A nickname for the sender identity. Not used for sending." + "format": "uri" }, - "from": { + "next": { + "type": "string", + "format": "uri" + }, + "count": { + "type": "integer", + "minimum": 0 + } + } + }, + "design-input": { + "title": "Design Input", + "allOf": [ + { + "$ref": "#/definitions/design-duplicate-input" + }, + { + "$ref": "#/definitions/design-common-fields" + }, + { "type": "object", "properties": { - "email": { + "html_content": { "type": "string", - "description": "This is where the email will appear to originate from for your recipient" + "description": "The HTML content of the Design.", + "maxLength": 1048576 }, - "name": { + "plain_content": { "type": "string", - "description": "This is the name appended to the from email field. IE - Your name or company name." + "description": "Plain text content of the Design.", + "maxLength": 1048576, + "default": "" } }, "required": [ - "email" + "html_content" ] + } + ], + "example": { + "name": "Ahoy, World!", + "editor": "design", + "subject": "Getting Started", + "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", + "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )" + } + }, + "design-output": { + "title": "Design Output", + "allOf": [ + { + "$ref": "#/definitions/design-output-summary" }, - "reply_to": { + { + "$ref": "#/definitions/design-input" + } + ] + }, + "design-output-summary": { + "title": "Design Output - Summary", + "allOf": [ + { "type": "object", "properties": { - "email": { + "id": { "type": "string", - "description": "This is the email that your recipient will reply to." + "description": "ID of the Design.", + "format": "uuid" }, - "name": { + "updated_at": { "type": "string", - "description": "This is the name appended to the reply to email field. IE - Your name or company name." + "description": "Datetime that Design was last updated.", + "format": "ISO 8601 date-time" + }, + "created_at": { + "type": "string", + "description": "Datetime that Design was created.", + "format": "ISO 8601 date-time" + }, + "thumbnail_url": { + "type": "string", + "description": "A Thumbnail preview of the template's html content." } } }, - "address": { - "type": "string", - "description": "The physical address of the sender identity." - }, - "address_2": { - "type": "string", - "description": "Additional sender identity address information." - }, - "city": { - "type": "string", - "description": "The city of the sender identity." - }, - "state": { - "type": "string", - "description": "The state of the sender identity." - }, - "zip": { - "type": "string", - "description": "The zipcode of the sender identity." - }, - "country": { - "type": "string", - "description": "The country of the sender identity." - }, - "verified": { - "type": "boolean", - "description": "If the sender identity is verified or not. Only verified sender identities can be used to send email." - }, - "updated_at": { - "type": "integer", - "description": "The time the sender identity was last updated." - }, - "created_at": { - "type": "integer", - "description": "The time the sender identity was created." - }, - "locked": { - "type": "boolean", - "description": "A sender identity is locked when it is associated to a campaign in the Draft, Scheduled, or In Progress status. You cannot update or delete a locked sender identity." + { + "$ref": "#/definitions/design-duplicate-input" + }, + { + "$ref": "#/definitions/design-common-fields" } - }, - "required": [ - "nickname", - "address", - "city", - "country" ], "example": { - "id": 1, - "nickname": "My Sender ID", - "from": { - "email": "from@example.com", - "name": "Example INC" - }, - "reply_to": { - "email": "replyto@example.com", - "name": "Example INC" - }, - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "state": "Colorado", - "zip": "80202", - "country": "United States", - "verified": true, - "updated_at": 1449872165, - "created_at": 1449872165, - "locked": false + "result": [ + { + "id": "3247eaea-c912-42a3-b0bc-60bdaf210396", + "name": "Welcome Email", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/llny8o5b3m636z92p7hbjnmq1jvpka39p370jwtin2s1wxv7x1sgm0y5fk518d0s.png", + "subject": "Welcom to the Cake or Pie Cafe", + "created_at": "2021-04-09T17:29:46Z", + "updated_at": "2021-04-09T17:29:55Z", + "editor": "code", + "categories": [ + "welcome", + "new customer" + ] + }, + { + "id": "02dfd792-f31f-439a-a79e-5c47fbcfdbac", + "name": "Monthly Promo", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/hfyxahd7ues2ajuoeoqq2xe6ibdasl1q89ox0y9ncya2ftpoicssmtf9ddus4c39.png", + "subject": "Free Dozen Cupcakes", + "created_at": "2021-04-09T17:29:21Z", + "updated_at": "2021-04-09T17:29:42Z", + "editor": "design", + "categories": [ + "promo", + "coupon" + ] + }, + { + "id": "e54be823-19ef-4c6f-8b60-efd7514f492d", + "name": "Duplicate: Ingrid & Anders", + "generate_plain_content": true, + "thumbnail_url": "//us-east-2-production-thumbnail-bucket.s3.amazonaws.com/12kni9gjpyb9uxmwr9vk7unycjr70u95zoyhe9sg2zounul2zg7dih1s20k13q2z.png", + "subject": "Welcome to Ingrid & Anders!", + "created_at": "2020-10-09T17:33:46Z", + "updated_at": "2021-04-07T19:57:52Z", + "editor": "design", + "categories": [] + } + ], + "_metadata": { + "self": "https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I", + "count": 3 + } } }, - "global:empty_request": { - "title": "Global: Request Empty Body", - "type": "null" - }, - "contactdb_custom_field": { - "title": "ContactDB Custom field schema.", + "design-duplicate-input": { + "title": "Design Duplicate Design Input", "type": "object", "properties": { "name": { "type": "string", - "description": "The name of the field" + "description": "The name of the new design.", + "default": "Duplicate: " }, - "type": { + "editor": { "type": "string", - "description": "The type of the field.", + "description": "The editor used in the UI.", "enum": [ - "date", - "text", - "number" + "code", + "design" ] } }, "example": { - "name": "first_name", - "type": "text" + "name": "Ahoy, Cake or Pie Cafe!", + "editor": "design" } }, - "whitelabel:domain_spf": { - "title": "Whitelabel - Domain", + "contact-details3": { + "title": "contact-details3", "type": "object", "properties": { "id": { - "type": "integer", - "description": "The ID of the domain whitelabel." + "type": "string" }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel was created for." + "first_name": { + "type": "string" }, - "subdomain": { - "type": "string", - "description": "The subdomain that was used to create this whitelabel." + "last_name": { + "type": "string" }, - "username": { - "type": "string", - "description": "The username of the account that this whitelabel is associated with." + "unique_name": { + "type": "string" }, - "user_id": { - "type": "integer", - "description": "The user_id of the account that this whitelabel is associated with." + "email": { + "type": "string" }, - "ips": { + "alternate_emails": { "type": "array", - "description": "The IP addresses that are included in the SPF record for this whitelabel.", - "items": {} + "items": { + "type": "string" + } }, - "custom_spf": { - "type": "boolean", - "description": "Indicates if this whitelabel uses custom SPF." + "address_line_1": { + "type": "string" }, - "default": { - "type": "boolean", - "description": "Indicates if this is the default whitelabel." + "address_line_2": { + "type": "string" }, - "legacy": { - "type": "boolean", - "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." + "city": { + "type": "string" }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this whitelabel uses automated security." + "state_province_region": { + "type": "string" }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." + "country": { + "type": "string" }, - "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." - } + "postal_code": { + "type": "string" + }, + "phone_number": { + "type": "string" + }, + "whatsapp": { + "type": "string" + }, + "line": { + "type": "string" + }, + "facebook": { + "type": "string" + }, + "list_ids": { + "type": "array", + "items": { + "type": "string" + } + }, + "segment_ids": { + "type": "array", + "items": { + "type": "string" + } + }, + "custom_fields": { + "type": "object" + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + }, + "_metadata": { + "$ref": "#/definitions/selfmetadata" + } + }, + "required": [ + "id", + "list_ids", + "segment_ids", + "created_at", + "updated_at" + ] + }, + "transactional-template-warning": { + "title": "Warning", + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Warning message for the user" + } + }, + "example": { + "message": "A sample warning message." + } + }, + "errors": { + "title": "Errors", + "type": "object", + "description": "If the request is incorrect, an array of errors will be returned.", + "properties": { + "errors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "parameter": { + "type": "string", + "description": "The parameter in the request body that is incorrect." + }, + "message": { + "type": [ + "string", + "null" + ], + "description": "A description of what is wrong with the field passed in the request." + }, + "field": { + "type": [ + "string", + "null" + ] } }, - "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." - } + "required": [ + "parameter", + "message" + ] + } + } + }, + "required": [ + "errors" + ] + }, + "singlesends-response": { + "title": "singlesends-response", + "type": "object", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "This is the ID of the Single Dend you require stats for.", + "format": "uuid" + }, + "ab_variation": { + "type": "string", + "default": "all", + "description": "This is the A/B variation of the Single Send stat returned. If the `group_by` parameter doesn't include `ab_variation` in the request, then the value is \"all\".", + "format": "uuid" + }, + "ab_phase": { + "type": "string", + "default": "all", + "description": "This is the A/B phase of the Single Send stat returned. If the `group_by` parameter doesn't include `ab_phase` in the request, then the value is \"all\".", + "enum": [ + "send", + "test", + "all" + ] + }, + "aggregation": { + "type": "string", + "description": "This describes the time unit to which the stat is rolled up. It is based on the `aggregated_by` parameter included in the request. It can be \"total\" or the date (in YYYY-MM-DD format) the stats are for.", + "default": "total" + }, + "stats": { + "$ref": "#/definitions/metrics" } }, - "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", + "ab_variation", + "ab_phase" + ] + } + }, + "_metadata": { + "$ref": "#/definitions/metadata" + } + }, + "required": [ + "results", + "_metadata" + ] + }, + "automations-response": { + "title": "automations-response", + "type": "object", + "properties": { + "results": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "This is the ID of the Automation you are requesting stats for.", + "format": "uuid" + }, + "aggregation": { + "type": "string", + "description": "This describes the time unit to which the stat is rolled up. It is based on the `aggregated_by` parameter included in the request. It can be \"total\" or the date (in YYYY-MM-DD format) the stats are for.", + "default": "total" + }, + "step_id": { + "type": "string", + "description": "This is the ID of the step if the stats were requested to be grouped by `step_id`.", + "default": "all" + }, + "stats": { + "$ref": "#/definitions/metrics" } - } + }, + "required": [ + "id", + "aggregation", + "step_id" + ] } + }, + "_metadata": { + "$ref": "#/definitions/metadata" } }, "required": [ - "id", - "domain", - "subdomain", - "username", - "user_id", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" + "results" ] }, - "subuser": { - "title": "List all Subusers for a parent response", + "metrics": { + "title": "metrics", "type": "object", "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not the user is enabled or disabled." + "bounce_drops": { + "type": "integer" }, - "id": { - "type": "number", - "description": "The ID of this subuser." + "bounces": { + "type": "integer" }, - "username": { - "type": "string", - "description": "The name by which this subuser will be referred." + "clicks": { + "type": "integer" }, - "email": { - "type": "string", - "description": "The email address to contact this subuser.", - "format": "email" + "delivered": { + "type": "integer" + }, + "invalid_emails": { + "type": "integer" + }, + "opens": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "spam_report_drops": { + "type": "integer" + }, + "spam_reports": { + "type": "integer" + }, + "unique_clicks": { + "type": "integer" + }, + "unique_opens": { + "type": "integer" + }, + "unsubscribes": { + "type": "integer" } }, "required": [ - "disabled", - "id", - "username", - "email" - ], - "example": { - "disabled": false, - "email": "example@example.com", - "id": 1234, - "username": "example_subuser" - } + "bounce_drops", + "bounces", + "clicks", + "delivered", + "invalid_emails", + "opens", + "requests", + "spam_report_drops", + "spam_reports", + "unique_clicks", + "unique_opens", + "unsubscribes" + ] }, - "mail_settings_address_whitelabel": { - "title": "Mail Settings: Address Whitelabel", + "singlesend_search": { + "title": "singlesend_search", "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you have an email address whitelist enabled. " + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "leading and trailing wildcard search on name of the Single Send" }, - "list": { + "status": { + "type": "array", + "description": "current status of the Single Send", + "uniqueItems": true, + "items": { + "type": "string", + "enum": [ + "draft", + "scheduled", + "triggered" + ] + } + }, + "categories": { "type": "array", - "description": "All email address that are currently on the whitelist.", + "description": "categories to associate with this Single Send, match any single send that has at least one of the categories", + "uniqueItems": true, "items": { "type": "string" } } - }, - "example": { - "enabled": true, - "list": [ - "email1@example.com", - "example.com" - ] } }, - "link_whitelabel": { - "title": "Whitelabel - Links", + "singlesend_request": { + "title": "singlesend_request", "type": "object", "properties": { - "id": { - "type": "integer", - "description": "The id of the link whitelabel." - }, - "domain": { + "name": { "type": "string", - "description": "The root domain for this link whitelabel." + "minLength": 1, + "maxLength": 100, + "description": "The name of the Single Send." }, - "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." + "categories": { + "type": "array", + "uniqueItems": true, + "maxItems": 10, + "description": "The categories to associate with this Single Send.", + "items": { + "type": "string" + } }, - "username": { + "send_at": { "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 - ] + "format": "date-time", + "description": "The ISO 8601 time at which to send the Single Send — this must be set for a future time." }, - "legacy": { - "type": "boolean", - "description": "Indicates if this link whitelabel was created using the legacy whitelabel tool.", - "enum": [ - true, - false - ] + "send_to": { + "type": "object", + "properties": { + "list_ids": { + "type": "array", + "description": "The recipient List IDs that will receive the Single Send.", + "maxItems": 10, + "items": { + "type": "string", + "format": "uuid" + } + }, + "segment_ids": { + "type": "array", + "description": "The recipient Segment IDs that will receive the Single Send.", + "maxItems": 10, + "items": { + "type": "string", + "format": "uuid" + } + }, + "all": { + "type": "boolean", + "description": "Set to `true` to send to All Contacts. If set to `false`, at least one `list_ids` or `segment_ids` value must be provided before the Single Send is scheduled to be sent to recipients.", + "default": false + } + } }, - "dns": { + "email_config": { "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" + "subject": { + "type": "string", + "description": "The subject line of the Single Send. Do not include this field when using a `design_id`." + }, + "html_content": { + "type": "string", + "description": "The HTML content of the Single Send. Do not include this field when using a `design_id`." + }, + "plain_content": { + "type": "string", + "description": "The plain text content of the Single Send. Do not include this field when using a `design_id`." + }, + "generate_plain_content": { + "type": "boolean", + "description": "If set to `true`, `plain_content` is always generated from `html_content`. If set to false, `plain_content` is not altered.", + "default": true + }, + "design_id": { + "type": "string", + "description": "A `design_id` can be used in place of `html_content`, `plain_content`, and/or `subject`. You can retrieve a design's ID from the [\"List Designs\" endpoint](https://sendgrid.api-docs.io/v3.0/designs-api/list-designs) or by pulling it from the design's detail page URL in the Marketing Campaigns App." + }, + "editor": { + "type": "string", + "enum": [ + "code", + "design" ], - "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." - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to." - } - } + "description": "The editor — `\"design\"` or `\"code\"` — used to modify the Single Send's design in the Marketing Campaigns App.", + "default": "code" + }, + "suppression_group_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the Suppression Group to allow recipients to unsubscribe — you must provide this or the `custom_unsubscribe_url`." + }, + "custom_unsubscribe_url": { + "type": [ + "string", + "null" + ], + "description": "The URL allowing recipients to unsubscribe — you must provide this or the `suppression_group_id`.", + "format": "uri" }, - "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." - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to." - } - }, - "required": [ - "valid", - "host", - "data" - ] + "sender_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the verified Sender. You can retrieve a verified Sender's ID from the [\"Get Verified Senders\" endpoint](https://sendgrid.api-docs.io/v3.0/sender-verification/get-verified-senders) or by pulling it from the Sender's detail page URL in the SendGrid App." + }, + "ip_pool": { + "type": [ + "string", + "null" + ], + "description": "The name of the IP Pool from which the Single Send emails are sent." } } } }, "required": [ - "id", - "domain", - "subdomain", - "username", - "user_id", - "default", - "valid", - "legacy", - "dns" + "name" ] }, - "email_object": { - "title": "Email Object", + "singlesend_schedule": { + "title": "singlesend-schedule", "type": "object", "properties": { - "email": { + "send_at": { "type": "string", - "format": "email" + "format": "date-time", + "description": "This is the ISO 8601 time at which to send the Single Send; must be in future, or the string \"now\"" }, - "name": { + "status": { "type": "string", - "description": "The name of the person to whom you are sending an email." + "enum": [ + "draft", + "scheduled", + "triggered" + ] } }, "required": [ - "email" + "send_at" ] }, - "api_key_name_id_scopes": { - "title": "API Key Name, ID, and Scopes", - "allOf": [ - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The permissions this API Key has access to.", - "items": { + "singlesend_warning": { + "title": "singlesend_warning", + "type": "object", + "properties": { + "warnings": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": "string" + }, + "warning_id": { "type": "string" } } } + } + } + }, + "to_email_array": { + "title": "To Email Array", + "type": "array", + "items": { + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email", + "description": "The intended recipient's email address." + }, + "name": { + "type": "string", + "description": "The intended recipient's name." + } }, + "required": [ + "email" + ] + }, + "example": [ { - "$ref": "#/definitions/api_key_name_id" + "email": "john_doe@example.com", + "name": "John Doe" } - ], - "example": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope", - "scopes": [ - "user.profile.read", - "user.profile.update" - ] - } + ] }, - "contactdb_segments": { - "title": "Create a Segment request", + "event-webhook-update-oauth-request": { + "title": "Webhooks: Event Webhook Update with OAuth Request", "type": "object", "properties": { - "name": { + "enabled": { + "type": "boolean", + "description": "Indicates if the event webhook is enabled." + }, + "url": { "type": "string", - "description": "The name of this segment." + "description": "The URL that you want the event webhook to POST to." }, - "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." + "group_resubscribe": { + "type": "boolean", + "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." }, - "conditions": { - "type": "array", - "description": "The conditions for a recipient to be included in this segment.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" - } + "delivered": { + "type": "boolean", + "description": "Message has been successfully delivered to the receiving server." }, - "recipient_count": { - "type": "number", - "description": "The count of recipients in this list. This is not included on creation of segments." + "group_unsubscribe": { + "type": "boolean", + "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." + }, + "spam_report": { + "type": "boolean", + "description": "Recipient marked a message as spam." + }, + "bounce": { + "type": "boolean", + "description": "Receiving server could not or would not accept message." + }, + "deferred": { + "type": "boolean", + "description": "Recipient's email server temporarily rejected message." + }, + "unsubscribe": { + "type": "boolean", + "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." + }, + "processed": { + "type": "boolean", + "description": "Message has been received and is ready to be delivered." + }, + "open": { + "type": "boolean", + "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." + }, + "click": { + "type": "boolean", + "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." + }, + "dropped": { + "type": "boolean", + "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" + }, + "oauth_client_id": { + "type": "string", + "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_token_url field." + }, + "oauth_client_secret": { + "type": "string", + "description": "This secret is needed only once to create an access token. SendGrid will store this secret, allowing you to update your Client ID and Token URL without passing the secret to SendGrid again. When passing data in this field, you must also include the oauth_client_id and oauth_token_url fields." + }, + "oauth_token_url": { + "type": "string", + "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id field." } }, "required": [ - "name", - "conditions" - ], - "example": { - "name": "Last Name Miller", - "list_id": 4, - "conditions": [ - { - "field": "last_name", - "value": "Miller", - "operator": "eq", - "and_or": "" - }, - { - "field": "last_clicked", - "value": "01/02/2015", - "operator": "gt", - "and_or": "and" - }, - { - "field": "clicks.campaign_identifier", - "value": "513", - "operator": "eq", - "and_or": "or" - } - ], - "recipient_count": 1234 - } + "enabled", + "url", + "group_resubscribe", + "delivered", + "group_unsubscribe", + "spam_report", + "bounce", + "deferred", + "unsubscribe", + "processed", + "open", + "click", + "dropped" + ] + }, + "webhooks-event-webhook-request": { + "title": "Webhooks: Event Webhook Request", + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Indicates if the event webhook is enabled." + }, + "url": { + "type": "string", + "description": "The URL that you want the event webhook to POST to." + }, + "group_resubscribe": { + "type": "boolean", + "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." + }, + "delivered": { + "type": "boolean", + "description": "Message has been successfully delivered to the receiving server." + }, + "group_unsubscribe": { + "type": "boolean", + "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." + }, + "spam_report": { + "type": "boolean", + "description": "Recipient marked a message as spam." + }, + "bounce": { + "type": "boolean", + "description": "Receiving server could not or would not accept message." + }, + "deferred": { + "type": "boolean", + "description": "Recipient's email server temporarily rejected message." + }, + "unsubscribe": { + "type": "boolean", + "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." + }, + "processed": { + "type": "boolean", + "description": "Message has been received and is ready to be delivered." + }, + "open": { + "type": "boolean", + "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." + }, + "click": { + "type": "boolean", + "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." + }, + "dropped": { + "type": "boolean", + "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" + }, + "oauth_client_id": { + "type": "string", + "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_token_url field." + }, + "oauth_token_url": { + "type": "string", + "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id field." + } + }, + "required": [ + "enabled", + "url", + "group_resubscribe", + "delivered", + "group_unsubscribe", + "spam_report", + "bounce", + "deferred", + "unsubscribe", + "processed", + "open", + "click", + "dropped" + ] }, - "api_key_name_id": { - "title": "API Key Name and ID", + "reply_to_email_object": { + "title": "Reply_to Email Object", "type": "object", "properties": { - "api_key_id": { + "email": { "type": "string", - "description": "The ID of your API Key. " + "format": "email", + "description": "The email address where any replies or bounces will be returned." }, "name": { "type": "string", - "description": "The name of your API Key." + "description": "A name or title associated with the `reply_to` email address." } }, + "required": [ + "email" + ], "example": { - "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", - "name": "A New Hope" + "email": "jane_doe@example.com", + "name": "Jane Doe" } }, - "advanced_stats_opens": { - "title": "Stats: Advanced Stats with Opens", + "automations-link-stats-response": { + "title": "automations-link-stats-response", "type": "object", "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { + "results": { "type": "array", - "description": "The statistics of the email events.", + "default": "", + "description": "", "items": { "type": "object", "properties": { - "type": { + "url": { "type": "string", - "description": "The type of segmentation." + "description": "This is the URL of the link clicked. If `{{custom_fields}}` are part of the URL, they will be included.", + "format": "uri" }, - "name": { + "url_location": { + "type": "integer", + "description": "This is the location of the link clicked in each Automation step. Links are located according to their position within the message; the topmost link has index `0`.", + "minimum": 0 + }, + "step_id": { "type": "string", - "description": "The name of the specific segmentation." + "description": "This is the ID of the step if the stats were requested to be grouped by `step_id`.", + "format": "uuid" }, - "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." - } - } + "clicks": { + "type": "integer", + "minimum": 1, + "description": "The number of clicks on this particular link." } }, "required": [ - "type", - "name", - "metrics" + "url", + "step_id", + "clicks" ] } + }, + "total_clicks": { + "type": "integer" + }, + "_metadata": { + "$ref": "#/definitions/link-tracking-metadata" } }, "required": [ - "date", - "stats" + "results", + "total_clicks", + "_metadata" ] }, - "mail_settings_template": { - "title": "Mail Settings: Template", + "link-tracking-metadata": { + "title": "link tracking metadata", "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the legacy email template setting is enabled." + "prev": { + "type": "string", + "format": "uri", + "description": "The URL of the previous page of results. If this field isn't present, you're at the start of the list." }, - "html_content": { + "self": { "type": "string", - "description": "The HTML content that you want to use for your legacy email template." - } - }, - "example": { - "enabled": false, - "html_content": "

<% body %>Example

\n" - } - }, - "ip_warmup_response": { - "title": "IP Warmup: IP", - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "start_date": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP address was entered into warmup mode." - } + "format": "uri", + "description": "The URL of the current page of results." }, - "required": [ - "ip", - "start_date" - ] - }, - "example": [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 + "next": { + "type": "string", + "format": "uri", + "description": "The URL of the next page of results. If this field isn't present, you're at the end of the list." + }, + "count": { + "type": "number", + "description": "The number of items in the entire list, i.e., across all pages." } - ] + } }, - "advanced_stats_mailbox_provider": { - "title": "Stats: Advanced Stats for Mailbox Provider", + "singlesends-link-stats-response": { + "title": "singlesends-link-stats-response", "type": "object", "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { + "results": { "type": "array", - "description": "The statistics of the email events.", + "default": "index", + "description": "This is the index of the link's location in the email contents.", "items": { "type": "object", "properties": { - "type": { + "url": { "type": "string", - "description": "The type of segmentation." + "description": "This is the URL of the link clicked. If `{{custom_fields}}` are part of the URL, they will be included.", + "format": "uri" }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." + "url_location": { + "type": "integer", + "description": "This is the location of the link clicked in each Single Send A/B variation, or in the Single Send itself if there are no variations. Links are numbered from the top down; the topmost link is index `0`.", + "minimum": 0 }, - "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" - ] - }, - "global:ErrorResponse": { - "title": "Global: Error Response", - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": [ - "string", - "null" - ], - "description": "The field that generated the error." + "ab_variation": { + "type": "string", + "description": "This is the A/B variation of the Single Send stat returned. It is set to `\"all\"` if the `ab_variation` query parameter was not set in the request and `group_by` doesn't contain `ab_variation`.", + "format": "uuid" }, - "message": { + "ab_phase": { "type": "string", - "description": "The error message." + "description": "This is the A/B phase of the Single Send stat returned. If the `ab_phase` query parameter was not provided, it will return `\"all\"`.", + "enum": [ + "send", + "test", + "all" + ] + }, + "clicks": { + "type": "integer", + "minimum": 1, + "description": "the number of clicks on this particular link" } }, "required": [ - "message" + "url", + "ab_variation", + "ab_phase", + "clicks" ] } - } - }, - "example": { - "errors": [ - { - "field": "field_name", - "message": "Some message here" - } - ] - } - }, - "contactdb_custom_field_with_id": { - "title": "ContactDB Custom field schema with ID.", - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field" }, - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the custom field." - } - } - } - ] - }, - "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" + "_metadata": { + "$ref": "#/definitions/link-tracking-metadata" }, - "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. " + "total_clicks": { + "type": "integer" } }, "required": [ - "email", - "frequency" - ], - "example": { - "email": "example@example.com", - "frequency": 50000 - } + "results", + "_metadata" + ] }, - "errors": { - "title": "Error Schema", - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { + "domain-authentication-200-response": { + "title": "Domain Authentication 200 Response", + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/definitions/authentication::domain" + }, + { "type": "object", "properties": { - "field": { - "type": [ - "null", - "string" - ], - "description": "The field that has the error." + "subusers": { + "type": "array", + "items": { + "type": "object", + "properties": { + "user_id": { + "type": "integer", + "description": "The ID of the subuser that this authenticated domain will be associated with." + }, + "username": { + "type": "string", + "description": "The username of the subuser that this authenticated domain is associated with." + } + } + } }, - "message": { - "type": "string", - "description": "The message the API caller will receive." + "last_validation_attempt_at": { + "type": "integer", + "description": "A Unix epoch timestamp representing the last time of a validation attempt." } } } - } - } - }, - "ip_pool": { - "title": "IP Pools: Pool", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the IP pool.", - "maxLength": 64 - } + ] }, - "required": [ - "name" + "example": [ + { + "id": 1, + "user_id": 7, + "subdomain": "mail", + "domain": "example.com", + "username": "jane@example.com", + "ips": [ + "192.168.1.1", + "192.168.1.2" + ], + "custom_spf": true, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": true, + "dns": { + "mail_cname": { + "valid": true, + "type": "cname", + "host": "mail.example.com", + "data": "u7.wl.sendgrid.net" + }, + "dkim1": { + "valid": true, + "type": "cname", + "host": "s1._domainkey.example.com", + "data": "s1._domainkey.u7.wl.sendgrid.net" + }, + "dkim2": { + "valid": true, + "type": "cname", + "host": "s2._domainkey.example.com", + "data": "s2._domainkey.u7.wl.sendgrid.net" + } + } + }, + { + "id": 2, + "user_id": 8, + "subdomain": "new", + "domain": "example2.com", + "username": "john@example2.com", + "ips": [], + "custom_spf": false, + "default": true, + "legacy": false, + "automatic_security": true, + "valid": false, + "dns": { + "mail_cname": { + "valid": false, + "type": "mx", + "host": "news.example2.com", + "data": "sendgrid.net" + }, + "dkim1": { + "valid": false, + "type": "txt", + "host": "example2.com", + "data": "k=rsa; t=s; p=publicKey" + }, + "dkim2": { + "valid": false, + "type": "txt", + "host": "example2.com", + "data": "k=rsa; t=s p=publicKey" + } + } + } ] }, - "google_analytics_settings": { - "title": "Settings: Google Analytics", - "type": "object", + "abtest_summary": { + "title": "abTest_summary", + "type": [ + "object", + "null" + ], "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if Google Analytics is enabled." - }, - "utm_campaign": { + "type": { "type": "string", - "description": "The name of the campaign." + "description": "What differs between the A/B tests", + "enum": [ + "subject", + "content" + ] }, - "utm_content": { + "winner_criteria": { "type": "string", - "description": "Used to differentiate ads" + "description": "How the winner will be decided", + "enum": [ + "open", + "click", + "manual" + ] }, - "utm_medium": { - "type": "string", - "description": "Name of the marketing medium (e.g. \"Email\")." + "test_percentage": { + "type": "integer", + "description": "What percentage of your recipient will be included in your A/B testing" }, - "utm_source": { + "duration": { "type": "string", - "description": "Name of the referrer source. " + "description": "How long the A/B Testing will last" }, - "utm_term": { + "winning_template_id": { "type": "string", - "description": "Any paid keywords." + "description": "Winner of the A/B Test" + }, + "winner_selected_at": { + "type": [ + "string", + "null" + ], + "description": "When the winner was selected" + }, + "expiration_date": { + "type": [ + "string", + "null" + ], + "description": "Last day to select an A/B Test Winner" } }, - "example": { - "enabled": true, - "utm_source": "sendgrid.com", - "utm_medium": "email", - "utm_term": "", - "utm_content": "", - "utm_campaign": "website" - } + "required": [ + "type", + "winner_criteria", + "test_percentage", + "duration", + "winning_template_id", + "winner_selected_at", + "expiration_date" + ] }, - "event_webhook_settings": { - "title": "Webhooks: Event Webhook Settings", + "singlesend_response_short": { + "title": "singlesend_response_short", "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the event webhook is enabled." - }, - "url": { + "id": { "type": "string", - "description": "The URL that you want the event webhook to POST to." - }, - "group_resubscribe": { - "type": "boolean", - "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." + "format": "uuid" }, - "delivered": { - "type": "boolean", - "description": "Message has been successfully delivered to the receiving server." - }, - "group_unsubscribe": { - "type": "boolean", - "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." - }, - "spam_report": { - "type": "boolean", - "description": "Recipient marked a message as spam." + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "name of the Single Send" }, - "bounce": { - "type": "boolean", - "description": "Receiving server could not or would not accept message." + "abtest": { + "$ref": "#/definitions/abtest_summary" }, - "deferred": { - "type": "boolean", - "description": "Recipient's email server temporarily rejected message." + "status": { + "type": "string", + "enum": [ + "draft", + "scheduled", + "triggered" + ], + "description": "current status of the Single Send" }, - "unsubscribe": { - "type": "boolean", - "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." + "categories": { + "type": "array", + "uniqueItems": true, + "maxItems": 10, + "description": "categories to associate with this Single Send", + "items": { + "type": "string" + } }, - "processed": { - "type": "boolean", - "description": "Message has been received and is ready to be delivered." + "send_at": { + "type": "string", + "format": "date-time", + "description": "the ISO 8601 time at which to send the Single Send; must be in future" }, - "open": { + "is_abtest": { "type": "boolean", - "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." + "description": "true if the Single Send's AB Test functionality has been toggled on" }, - "click": { - "type": "boolean", - "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." + "updated_at": { + "type": "string", + "description": "the ISO 8601 time at which the Single Send was last updated", + "format": "date-time" }, - "dropped": { - "type": "boolean", - "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" + "created_at": { + "type": "string", + "description": "the ISO 8601 time at which the Single Send was created", + "format": "date-time" } }, "required": [ - "enabled", - "url", - "group_resubscribe", - "delivered", - "group_unsubscribe", - "spam_report", - "bounce", - "deferred", - "unsubscribe", - "processed", - "open", - "click", - "dropped" + "id", + "name", + "abtest", + "status", + "categories", + "is_abtest", + "updated_at", + "created_at" ] }, - "user_profile": { - "title": "User: Profile", + "cc_bcc_email_object": { + "title": "CC BCC Email Object", "type": "object", "properties": { - "address": { + "email": { "type": "string", - "description": "The street address for this user profile." + "format": "email", + "description": "The intended recipient's email address." }, - "address2": { + "name": { "type": "string", - "description": "An optional second line for the street address of this user profile." + "description": "The intended recipient's name." + } + }, + "required": [ + "email" + ], + "example": { + "email": "jane_doe@example.com", + "name": "Jane Doe" + } + }, + "verified-sender-request-schema": { + "title": "Verified Sender Request Schema", + "type": "object", + "properties": { + "nickname": { + "type": "string", + "maxLength": 100 }, - "city": { + "from_email": { "type": "string", - "description": "The city for the user profile." + "maxLength": 256, + "format": "email" }, - "company": { + "from_name": { "type": "string", - "description": "That company that this user profile is associated with." + "maxLength": 256 }, - "country": { + "reply_to": { "type": "string", - "description": "Th country of this user profile." + "maxLength": 256, + "format": "email" }, - "first_name": { + "reply_to_name": { "type": "string", - "description": "The first name of the user." + "maxLength": 256 }, - "last_name": { + "address": { "type": "string", - "description": "The last name of the user." + "maxLength": 100 }, - "phone": { + "address2": { "type": "string", - "description": "The phone number for the user." + "maxLength": 100 }, "state": { "type": "string", - "description": "The state for this user." + "maxLength": 2 }, - "website": { + "city": { "type": "string", - "description": "The website associated with this user." + "maxLength": 150 }, "zip": { "type": "string", - "description": "The zip code for this user." + "maxLength": 10 + }, + "country": { + "type": "string", + "maxLength": 100 } }, + "required": [ + "nickname", + "from_email", + "reply_to" + ], "example": { - "address": "1451 Larimer Street, 3rd floor", - "address2": "", - "city": "Denver, CO", - "company": "SendGrid", - "country": "US", - "first_name": "Matthew", - "last_name": "Bernier", - "phone": "7208788003", - "state": "CO", - "website": "http://sendgrid.com", - "zip": "80202" + "nickname": "Orders", + "from_email": "orders@example.com", + "from_name": "Example Orders", + "reply_to": "orders@example.com", + "reply_to_name": "Example Orders", + "address": "1234 Fake St", + "address2": "PO Box 1234", + "state": "CA", + "city": "San Francisco", + "country": "USA", + "zip": "94105" } }, - "mail_settings_footer": { - "title": "Mail Settings: Footer", + "verified-sender-response-schema": { + "title": "Verified Sender Response Schema", "type": "object", "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the Footer mail setting is currently enabled." + "id": { + "type": "integer" + }, + "nickname": { + "type": "string" + }, + "from_email": { + "type": "string" + }, + "from_name": { + "type": "string" + }, + "reply_to": { + "type": "string" + }, + "reply_to_name": { + "type": "string" }, - "html_content": { - "type": "string", - "description": "The custom HTML content of your email footer." + "address": { + "type": "string" }, - "plain_content": { - "type": "string", - "description": "The plain text content of your email footer." + "address2": { + "type": "string" + }, + "state": { + "type": "string" + }, + "city": { + "type": "string" + }, + "zip": { + "type": "string" + }, + "country": { + "type": "string" + }, + "verified": { + "type": "boolean" + }, + "locked": { + "type": "boolean" } }, "example": { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" + "id": 1234, + "nickname": "Example Orders", + "from_email": "orders@example.com", + "from_name": "Example Orders", + "reply_to": "orders@example.com", + "reply_to_name": "Example Orders", + "address": "1234 Fake St.", + "address2": "PO Box 1234", + "state": "CA", + "city": "San Francisco", + "country": "USA", + "zip": "94105", + "verified": true, + "locked": false } }, - "category_stats": { - "title": "Stats: Category Stats", + "ip-access-response": { + "title": "IP Access Response", "type": "object", "properties": { - "date": { - "type": "string", - "description": "The date the statistics were gathered." - }, - "stats": { + "result": { "type": "array", + "description": "An array listing all of your allowed IPs.", "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" - ] + "id": { + "type": "integer", + "description": "The ID of the allowed IP." }, - "name": { + "ip": { "type": "string", - "description": "The name of the category." + "description": "The allowed IP." }, - "type": { - "type": "string", - "description": "How you are segmenting your statistics." + "created_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the IP was added to the allow list." + }, + "updated_at": { + "type": "integer", + "description": "A Unix timestamp indicating when the IPs allow status was most recently updated." } - }, - "required": [ - "type" - ] + } } } }, - "required": [ - "date" - ], "example": { - "date": "2015-01-01", - "stats": [ + "result": [ { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "cat1", - "type": "category" + "id": 1, + "ip": "192.168.1.1/32", + "created_at": 1441824715, + "updated_at": 1441824715 }, { - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - }, - "name": "cat2", - "type": "category" + "id": 2, + "ip": "192.0.0.0/8", + "created_at": 1441824715, + "updated_at": 1441824715 + }, + { + "id": 3, + "ip": "192.168.1.3/32", + "created_at": 1441824715, + "updated_at": 1441824715 } ] } }, - "transactional_template": { - "title": "Transactional Templates: 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 + "stats-advanced-global-stats": { + "title": "Stats: Advanced Global Stats", + "allOf": [ + { + "$ref": "#/definitions/advanced_stats_clicks_opens" }, - "versions": { - "type": "array", - "description": "The different versions of this transactional template.", - "items": { - "$ref": "#/definitions/transactional_template_version" + { + "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." + }, + "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." + }, + "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." + }, + "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": [ - "id", - "name" ] - }, - "parse-setting": { - "title": "Parse Setting", - "type": "object", - "properties": { - "url": { - "type": "string", - "description": "The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL." - }, - "hostname": { - "type": "string", - "description": "A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, parse.yourdomain.com." - }, - "spam_check": { - "type": "boolean", - "description": "Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain." - }, - "send_raw": { - "type": "boolean", - "description": "Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to \"false\", SendGrid will send a JSON payload of the content of your email. " + }, + "stats-advanced-stats-base-schema": { + "title": "Stats: Advanced Stats Base 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" + } + } + } + } } - }, - "example": { - "url": "http://email.myhostname.com", - "hostname": "myhostname.com", - "spam_check": false, - "send_raw": true } }, - "contactdb_list": { - "title": "ContactDB lists", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The reference ID of your list." + "full-segment": { + "title": "full_segment", + "allOf": [ + { + "$ref": "#/definitions/segment_summary" }, - "name": { - "type": "string", - "description": "The name of your list." + { + "type": "object", + "properties": { + "contacts_sample": { + "type": "array", + "items": { + "$ref": "#/definitions/contact_response" + } + }, + "query_json": { + "type": "object", + "description": "AST representation of the query DSL" + } + }, + "required": [ + "contacts_sample" + ] }, - "recipient_count": { - "type": "integer", - "description": "The count of recipients currently in the list." + { + "$ref": "#/definitions/segment_write" } - }, - "required": [ - "id", - "name", - "recipient_count" ], "example": { - "id": 1, - "name": "listname", - "recipient_count": 0 + "id": "58567a46-305e-48d1-b4f8-a006c906920e", + "contacts_count": 9266921, + "created_at": "2085-08-08T21:07:05.692Z", + "sample_updated_at": "3407-09-25T04:25:02.140Z", + "updated_at": "4431-05-07T22:23:22.352Z", + "contacts_sample": [ + { + "contact_id": "c1183ada-b784-49ac-9b1f-50e73578a6dc", + "primary_email": "ft88@d.izxx", + "alternate_emails": [ + "yKDUP11FDch@QoU.vwy", + "ZNSN5@czAMqPi.at", + "7wr51kFVVKlcBSH@DWxOueOZepetzBrku.qosk", + "iib-ObtO7Fxz5@vLJPRIFKPOqJGCEqcIDab.ypn" + ], + "first_name": "est", + "last_name": "eiusmod in laboris velit cupidatat", + "address_line_1": "sunt aliqua", + "address_line_2": "sit proident Lorem veniam labore", + "city": "œȎţȸÛ\tč\u000bCŁ", + "state_province_region": "ut proident", + "postal_code": 30296612, + "country": "do reprehenderit qui", + "custom_fields": { + "custom_field_name2": "in consectetur ut aliqua sint", + "custom_field_name1": "esse" + } + } + ], + "name": "culpa", + "query_dsl": "cillum eiusmod", + "parent_list_id": "2357714d-3d82-4c80-826c-b44a4147f81c", + "next_sample_update": "" } }, - "suppression_group": { - "title": "Suppressions: Suppression Group", + "senders-id-request-body": { + "title": "Senders ID Request Body", "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": { + "nickname": { "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" - ] - }, - "mail_settings_bounce_purge": { - "title": "Mail Settings: Bounce Purge", - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the bounce purge mail setting is enabled." + "description": "A nickname for the sender identity. Not used for sending." }, - "soft_bounces": { - "type": [ - "integer", - "null" + "from": { + "type": "object", + "required": [ + "email", + "name" ], - "description": "The number of days, after which SendGrid will purge all contacts from your soft bounces suppression lists." + "properties": { + "email": { + "type": "string", + "description": "This is where the email will appear to originate from for your recipient" + }, + "name": { + "type": "string", + "description": "This is the name appended to the from email field. IE - Your name or company name." + } + } }, - "hard_bounces": { - "type": [ - "integer", - "null" - ], - "description": "The number of days, after which SendGrid will purge all contacts from your hard bounces suppression lists." - } - }, - "example": { - "enabled": false, - "soft_bounces": 1234, - "hard_bounces": null - } - }, - "transactional_template_version": { - "title": "Transactional Templates: Version", - "type": "object", - "properties": { - "template_id": { + "reply_to": { + "type": "object", + "properties": { + "email": { + "type": "string", + "description": "This is the email that your recipient will reply to." + }, + "name": { + "type": "string", + "description": "This is the name appended to the reply to email field. IE - Your name or company name." + } + }, + "required": [ + "email" + ] + }, + "address": { "type": "string", - "description": "The name of the original transactional template." + "description": "The physical address of the sender identity." }, - "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 - ] + "address_2": { + "type": "string", + "description": "Additional sender identity address information." }, - "name": { + "city": { "type": "string", - "description": "Name of the new transactional template version." + "description": "The city of the sender identity." }, - "html_content": { + "state": { "type": "string", - "description": "The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." + "description": "The state of the sender identity." }, - "plain_content": { + "zip": { "type": "string", - "description": "Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." + "description": "The zipcode of the sender identity." }, - "subject": { + "country": { "type": "string", - "description": "Subject of the new transactional template version. Must include <%subject%> tag." + "description": "The country of the sender identity." } }, "required": [ - "template_id", - "active", - "name", - "html_content", - "plain_content", - "subject" + "nickname", + "from", + "address", + "city", + "country" ] }, - "mail_settings_bcc": { - "title": "Mail Settings: BCC", + "enforced-tls-request-response": { + "title": "Enforced TLS Request Response", "type": "object", "properties": { - "email": { - "type": "string", - "description": "The email address that will be sent a blind carbon copy." + "require_tls": { + "type": "boolean", + "description": "Indicates if you want to require your recipients to support TLS. " }, - "enabled": { + "require_valid_cert": { "type": "boolean", - "description": "Indicates if the BCC setting is enabled." + "description": "Indicates if you want to require your recipients to have a valid certificate." } - }, - "example": { - "email": "example@example.com", - "enabled": false } }, - "global:id": { - "title": "Global: ID", - "type": "integer" - }, - "credentials": { - "title": "Credentials", - "type": "object", - "properties": { - "permissions": { + "singlesend_response": { + "title": "singlesend_response", + "allOf": [ + { + "$ref": "#/definitions/singlesend_request" + }, + { "type": "object", "properties": { - "api": { - "type": "string" + "id": { + "type": "string", + "format": "uuid" }, - "mail": { - "type": "string" + "status": { + "type": "string", + "enum": [ + "draft", + "scheduled", + "triggered" + ], + "description": "current status of the Single Send" }, - "web": { - "type": "string" - } - } - }, - "username": { - "type": "string" - } - }, - "example": { - "address": "1234 example street", - "address2": null, - "city": "Denver", - "company": "Company name", - "country": "US", - "email": "example@example.com", - "first_name": "Example", - "last_name": "User", - "phone": "(555) 555-5555", - "state": "CO", - "zip": "55555" - } - }, - "subuser_stats": { - "title": "subuser_stats", - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "first_name": { - "type": "string", - "description": "The first name of the subuser." - }, - "last_name": { - "type": "string", - "description": "The last name of the subuser." - }, - "metrics": { + "updated_at": { + "type": "string", + "description": "the ISO 8601 time at which the Single Send was last updated", + "format": "date-time" + }, + "created_at": { + "type": "string", + "description": "the ISO 8601 time at which the Single Send was created", + "format": "date-time" + }, + "warnings": { + "type": "array", + "items": { "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." + "message": { + "type": "string" }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." + "field": { + "type": "string" }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." + "warning_id": { + "type": "string" } } - }, - "name": { - "type": "string", - "description": "The username of the subuser." - }, - "type": { + } + } + }, + "required": [ + "id", + "status", + "created_at" + ] + } + ], + "example": { + "name": "Example API Created Single Send", + "id": "27c21bbf-a12c-440b-b8bf-c526975328ca", + "status": "scheduled", + "created_at": "2020-05-18T17:28:27.272Z", + "send_at": "2020-06-16T00:19:55.106Z", + "categories": [ + "unique opens" + ], + "email_config": { + "subject": "", + "html_content": "", + "plain_content": "", + "generate_plain_content": true, + "editor": "code", + "suppression_group_id": null, + "custom_unsubscribe_url": null, + "sender_id": null, + "ip_pool": null + }, + "send_to": { + "list_ids": [ + "f2fe66a1-43f3-4e3a-87b1-c6a600d805f0" + ] + } + } + }, + "design-common-fields": { + "title": "Design Common Fields", + "allOf": [ + { + "$ref": "#/definitions/design-duplicate-input" + }, + { + "type": "object", + "properties": { + "generate_plain_content": { + "type": "boolean", + "description": "If true, plain_content is always generated from html_content. If false, plain_content is not altered.", + "default": true + }, + "subject": { + "type": "string", + "description": "Subject of the Design.", + "maxLength": 5000 + }, + "categories": { + "type": "array", + "description": "The list of categories applied to the design", + "uniqueItems": true, + "maxItems": 10, + "items": { "type": "string", - "description": "The type of account." + "maxLength": 255 } } } } + ] + }, + "invalid-email": { + "title": "Invalid Email", + "type": "object", + "properties": { + "created": { + "type": "integer", + "description": "A Unix timestamp indicating when the email address was added to the invalid emails list." + }, + "email": { + "type": "string", + "description": "The email address that was marked as invalid.", + "format": "email" + }, + "reason": { + "type": "string", + "description": "The reason that the email address was marked as invalid." + } + }, + "example": { + "created": 1620141015, + "email": "invalid@example.com", + "reason": "Mail domain mentioned in email address is unknown" } }, - "campaign_request": { - "title": "Campaigns Request", + "email-activity-response-common-fields": { + "title": "Email Activity Response Common Fields", "type": "object", "properties": { - "title": { + "from_email": { "type": "string", - "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." + "format": "email", + "default": "", + "description": "The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account." }, - "subject": { - "type": [ - "string", - "null" - ], - "description": "The subject of your campaign that your recipients will see." + "msg_id": { + "type": "string", + "description": "A unique ID assigned to the message. This ID can be used to retrieve activity data for the specific message." }, - "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." + "subject": { + "type": "string", + "description": "The email's subject line." }, - "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" - } + "to_email": { + "type": "string", + "format": "email", + "description": "The intended recipient's email address." }, - "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.", + "status": { + "type": "string", + "description": "The message's status.", + "enum": [ + "processed", + "delivered", + "not delivered" + ] + } + } + }, + "suppressions-request": { + "title": "Suppressions Request Body", + "type": "object", + "properties": { + "recipient_emails": { + "type": "array", + "description": "The array of email addresses to add or find.", "items": { - "type": "integer" + "type": "string", + "format": "email" } + } + }, + "required": [ + "recipient_emails" + ], + "example": { + "recipient_emails": [ + "test1@example.com", + "test2@example.com" + ] + } + }, + "suppression-group-request-base": { + "title": "Suppression Group Request Base", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of your suppression group. Required when creating a group.", + "maxLength": 30 }, - "categories": { - "type": [ - "array", - "null" - ], - "description": "The categories you would like associated to this campaign.", - "items": { - "type": "string" - } + "description": { + "type": "string", + "description": "A brief description of your suppression group. Required when creating a group.", + "maxLength": 100 }, - "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." + "is_default": { + "type": "boolean", + "description": "Indicates if you would like this to be your default suppression group." + } + } + }, + "sso-certificate-body": { + "title": "Single Sign-On Certificate Body", + "type": "object", + "properties": { + "public_certificate": { + "type": "string", + "description": "This certificate is used by Twilio SendGrid to verify that SAML requests are coming from Okta. This is called the X509 certificate in the Twilio SendGrid UI." }, - "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." + "id": { + "type": "number", + "description": "A unique ID assigned to the certificate by SendGrid." }, - "ip_pool": { - "type": [ - "string", - "null" - ], - "description": "The pool of IPs that you would like to send this email from." + "not_before": { + "type": "number", + "description": "A unix timestamp (e.g., 1603915954) that indicates the time before which the certificate is not valid." }, - "html_content": { - "type": [ - "string", - "null" - ], - "description": "The HTML of your marketing email." + "not_after": { + "type": "number", + "description": "A unix timestamp (e.g., 1603915954) that indicates the time after which the certificate is no longer valid." }, - "plain_content": { - "type": [ - "string", - "null" - ], - "description": "The plain text content of your emails." - } - }, - "required": [ - "title" - ], - "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" + "intergration_id": { + "type": "string", + "description": "An ID that matches a certificate to a specific IdP integration." + } + }, + "example": { + "public_certificate": "", + "id": 66138975, + "not_before": 1621289880, + "not_after": 1621289880, + "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } }, - "user_scheduled_send_status": { - "title": "User: Scheduled Send status", + "sso-integration": { + "title": "Single Sign-On Integration", "allOf": [ { - "$ref": "#/definitions/mail_batch_id" + "$ref": "#/definitions/create-integration-request" }, { "type": "object", - "description": "The status of the scheduled send.", "properties": { - "status": { + "last_updated": { + "type": "number", + "description": "A timestamp representing the last time the configuration was modified." + }, + "id": { "type": "string", - "description": "The status of the scheduled send.", - "enum": [ - "cancel", - "pause" - ] + "description": "A unique ID assigned to the configuration by SendGrid." + }, + "single_signon_url": { + "type": "string", + "description": "The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Audience URL when using SendGrid." + }, + "audience_url": { + "type": "string", + "description": "The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Single Sign-On URL when using SendGrid." } }, "required": [ - "status" + "last_updated" ] } ] }, - "mail_settings_forward_spam": { - "title": "Mail Settings: Forward Spam", + "create-integration-request": { + "title": "Create Integration Request", "type": "object", "properties": { - "email": { + "name": { "type": "string", - "description": "The email address where you would like the spam reports to be forwarded." + "description": "The name of your integration. This name can be anything that makes sense for your organization (eg. Twilio SendGrid)" }, "enabled": { "type": "boolean", - "description": "Indicates if the Forward Spam setting is enabled." + "description": "Indicates if the integration is enabled." + }, + "signin_url": { + "type": "string", + "description": "The IdP's SAML POST endpoint. This endpoint should receive requests and initiate an SSO login flow. This is called the \"Embed Link\" in the Twilio SendGrid UI." + }, + "signout_url": { + "type": "string", + "description": "This URL is relevant only for an IdP-initiated authentication flow. If a user authenticates from their IdP, this URL will return them to their IdP when logging out." + }, + "entity_id": { + "type": "string", + "description": "An identifier provided by your IdP to identify Twilio SendGrid in the SAML interaction. This is called the \"SAML Issuer ID\" in the Twilio SendGrid UI." + }, + "completed_integration": { + "type": "boolean", + "description": "Indicates if the integration is complete." } }, - "example": { - "email": "", - "enabled": true - } + "required": [ + "name", + "enabled", + "signin_url", + "signout_url", + "entity_id" + ] }, - "contactdb_segments_with_id": { - "title": "ContactDB:: Segments with ID", + "sso-teammate-response": { + "title": "Single Sign-On Teammate Response", "allOf": [ + { + "$ref": "#/definitions/sso-teammate-common-fields" + }, { "type": "object", "properties": { - "id": { - "type": "number", - "description": "The ID of the segment." + "username": { + "type": "string", + "description": "This should be set to the Teammate's email address." + }, + "is_sso": { + "type": "boolean", + "description": "Indicates if the Teammate authenticates with SendGrid using SSO or with a username and password." } - }, - "required": [ - "id" - ] - }, - { - "$ref": "#/definitions/contactdb_segments" + } } ] }, - "advanced_stats_country": { - "title": "Stats: Advanced Stats with Clicks and Opens", - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." + "sso-teammate-request": { + "title": "Single Sign-On Teammate Request", + "allOf": [ + { + "$ref": "#/definitions/sso-teammate-common-fields" }, - "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." - } - } + { + "type": "object", + "properties": { + "scopes": { + "type": "array", + "description": "The permission scopes assigned to the Teammate.", + "items": { + "type": "string" } - }, - "required": [ - "type", - "name", - "metrics" - ] - } + } + }, + "required": [ + "scopes" + ] } - }, - "required": [ - "date", - "stats" ] }, - "advanced_stats_clicks": { - "title": "Stats: Advanced Stats with Clicks", - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." + "sso-teammates-patch-response": { + "title": "Single Sign-On Teammates PATCH Response", + "allOf": [ + { + "$ref": "#/definitions/sso-teammate-response" }, - "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." - } - } - } + { + "type": "object", + "properties": { + "address": { + "type": "string", + "description": "The Teammate’s street address." }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - }, - "contactdb_recipient": { - "title": "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." + "address2": { + "type": "string", + "description": "The Teammate’s apartment number, suite number, or other secondary address information that is not part of the physical street address." + }, + "city": { + "type": "string", + "description": "The Teammate's city." + }, + "company": { + "type": "string", + "description": "The Teammate’s company name." + }, + "country": { + "type": "string", + "description": "The Teammate’s country of residence." + }, + "email": { + "type": "string", + "format": "email" + }, + "phone": { + "type": "string", + "description": "The Teammate’s stored phone number." + }, + "scopes": { + "type": "array", + "description": "The permission scopes assigned to the Teammate.", + "items": { + "type": "string" } }, - "required": [ - "email" + "state": { + "type": "string", + "description": "The Teammate’s state or province." + }, + "user_type": { + "type": "string", + "description": "A Teammate can be an “admin,” “owner,” or “teammate.” Each role is associated with the scope of the Teammate’s permissions.", + "enum": [ + "admin", + "owner", + "teammate" + ] + }, + "website": { + "type": "string", + "description": "A website associated with the Teammate" + }, + "zip": { + "type": "string", + "description": "The Teammate’s zip code." + } + } + } + ] + }, + "sso-error-response": { + "title": "SSO Error Response", + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "field": { + "type": [ + "string", + "null" ] + }, + "error_id": { + "type": "string" } } } }, - "mail_settings_patch": { - "title": "Mail Settings: Patch", + "click-tracking": { + "title": "Settings: Click Tracking", "type": "object", "properties": { - "enabled": { + "enable_text": { "type": "boolean", - "description": "Indicates if the mail setting is enabled." + "description": "Indicates if click tracking is enabled for plain text emails." }, - "email": { - "type": "string", - "description": "The email address of the recipient." + "enabled": { + "type": "boolean", + "description": "Indicates if click tracking is enabled or disabled." } }, + "required": [ + "enable_text", + "enabled" + ], "example": { - "enabled": true, - "email": "email@example.com" + "enable_text": false, + "enabled": false } }, - "mail_settings_forward_bounce": { - "title": "Mail Settings: Forward Bounce", + "sso-teammate-common-fields": { + "title": "Single Sing-On Teammate Common Fields", "type": "object", "properties": { + "first_name": { + "type": "string", + "description": "The Teammate’s first name." + }, + "last_name": { + "type": "string", + "description": "The Teammate’s last name." + }, "email": { - "type": [ - "string", - "null" - ], - "description": "The email address that you would like your bounce reports forwarded to." + "type": "string", + "format": "email", + "description": "The Teammate’s email address. This email address will also function as the Teammate’s username and must match the address assigned to the user in your IdP. This address cannot be changed after the Teammate is created." }, - "enabled": { + "is_admin": { "type": "boolean", - "description": "Indicates if the bounce forwarding mail setting is enabled." + "description": "Indicates if the Teammate has admin permissions." + }, + "is_read_only": { + "type": "boolean", + "description": "Indicates if the Teammate has read_only permissions." } }, - "example": { - "enabled": false, - "email": null - } + "required": [ + "first_name", + "last_name", + "email" + ] }, - "contactdb_custom_field_with_id_value": { - "title": "ContactDB Custom field schema.", - "allOf": [ + "spam-reports-response": { + "title": "Spam Reports Response", + "type": "array", + "items": { + "type": "object", + "properties": { + "created": { + "type": "integer", + "description": "A Unix timestamp that indicates when the recipient marked your message as spam." + }, + "email": { + "type": "string", + "description": "The email address of the recipient that marked your message as spam.", + "format": "email" + }, + "ip": { + "type": "string", + "description": "The IP address that the message was sent from." + } + }, + "required": [ + "created", + "email", + "ip" + ] + }, + "example": [ { - "$ref": "#/definitions/contactdb_custom_field_with_id" + "created": 1443651141, + "email": "user1@example.com", + "ip": "10.63.202.100" }, { - "type": "object", - "properties": { - "value": { - "type": [ - "string", - "null" - ], - "description": "The value of this recipient's custom field" - } + "created": 1443651154, + "email": "user2@example.com", + "ip": "10.63.202.100" + } + ] + }, + "blocks-response": { + "title": "Blocks Response", + "type": "array", + "items": { + "type": "object", + "properties": { + "created": { + "type": "integer", + "description": "A Unix timestamp indicating when the email address was added to the blocks list." + }, + "email": { + "type": "string", + "description": "The email address that was added to the block list.", + "format": "email" + }, + "reason": { + "type": "string", + "description": "An explanation for the reason of the block." + }, + "status": { + "type": "string", + "description": "The status of the block." } + }, + "required": [ + "created", + "email", + "reason", + "status" + ] + }, + "example": [ + { + "created": 1443651154, + "email": "example@example.com", + "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", + "status": "4.0.0" } ] }, - "contactdb_recipient_count": { - "title": "ContactDB: Recipient Count", + "ip_pool_response": { + "title": "IP Pools: Pool Resp", "type": "object", "properties": { - "recipient_count": { - "type": "number", - "description": "The count of recipients." + "name": { + "type": "string", + "description": "The name of the IP pool." } - }, - "required": [ - "recipient_count" - ], - "example": { - "recipient_count": 1234 } }, - "subuser_post": { - "title": "Subuser::POST", - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the subuser." + "stats": { + "title": "stats", + "type": "array", + "items": { + "type": "object", + "properties": { + "date": { + "type": "string" + }, + "stats": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "name": { + "type": "string" + }, + "metrics": { + "type": "object", + "properties": { + "blocks": { + "type": "integer" + }, + "bounce_drops": { + "type": "integer" + }, + "bounces": { + "type": "integer" + }, + "clicks": { + "type": "integer" + }, + "deferred": { + "type": "integer" + }, + "delivered": { + "type": "integer" + }, + "invalid_emails": { + "type": "integer" + }, + "opens": { + "type": "integer" + }, + "processed": { + "type": "integer" + }, + "requests": { + "type": "integer" + }, + "spam_report_drops": { + "type": "integer" + }, + "spam_reports": { + "type": "integer" + }, + "unique_clicks": { + "type": "integer" + }, + "unique_opens": { + "type": "integer" + }, + "unsubscribe_drops": { + "type": "integer" + }, + "unsubscribes": { + "type": "integer" + } + } + } + } + } + } + } + }, + "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 + } + } + ] }, - "user_id": { - "type": "number", - "description": "The user ID for this subuser." + { + "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 + } + } + ] + } + ] + }, + "abbv-message": { + "title": "Abbv. Message", + "type": "object", + "properties": { + "from_email": { + "type": "string" }, - "email": { - "type": "string", - "description": "The email address for this subuser.", - "format": "email" + "msg_id": { + "type": "string" }, - "signup_session_token": { + "subject": { "type": "string" }, - "authorization_token": { + "to_email": { "type": "string" }, - "credit_allocation": { - "type": "object", - "properties": { - "type": { - "type": "string" - } - } + "status": { + "type": "string", + "enum": [ + "processed", + "delivered", + "not_delivered" + ] + }, + "opens_count": { + "type": "integer" + }, + "clicks_count": { + "type": "integer" + }, + "last_event_time": { + "type": "string", + "description": "iso 8601 format" } }, "required": [ - "username", - "user_id", - "email" + "from_email", + "msg_id", + "subject", + "to_email", + "status", + "opens_count", + "clicks_count", + "last_event_time" ], "example": { - "username": "example_subuser", - "user_id": 1234, - "email": "example@example.com", - "signup_session_token": "", - "authorization_token": "", - "credit_allocation": { - "type": "unlimited" - } + "from_email": "from@test.com", + "msg_id": "abc123", + "subject": "anim Duis sint veniam", + "to_email": "test@test.com", + "status": "processed", + "opens_count": 1, + "clicks_count": 2, + "last_event_time": "2017-10-13T18:56:21Z" } }, - "whitelabel::domain": { - "title": "Whitelabel - Domain", + "message": { + "title": "Message", "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": { + "from_email": { "type": "string", - "description": "The subdomain to use for this domain whitelabel." + "pattern": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b" }, - "domain": { + "msg_id": { "type": "string", - "description": "The domain that this whitelabel is being created for." + "minLength": 5, + "maxLength": 50, + "pattern": "^[A-Za-z0-9]+" }, - "username": { + "subject": { "type": "string", - "description": "The username that this whitelabel will be associated with." + "minLength": 3, + "maxLength": 255 }, - "ips": { - "type": "array", - "description": "The IPs to be included in the custom SPF record for this domain whitelabel.", - "items": { - "type": "object" - } + "to_email": { + "type": "string", + "pattern": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b" }, - "custom_spf": { - "type": "boolean", - "description": "Indicates whether this domain whitelabel will use custom SPF." + "status": { + "type": "string", + "description": "Quick summary of the status of a message", + "enum": [ + "processed", + "not delivered", + "delivered" + ] }, - "default": { - "type": "boolean", - "description": "Indicates if this domain whitelabel is the default whitelabel." + "template_id": { + "type": "string", + "format": "uuid" }, - "legacy": { - "type": "boolean", - "description": "Indicates if this domain whitelabel was created using the legacy whitelabel tool." + "asm_group_id": { + "type": "integer", + "minimum": 1 }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this domain whitelabel uses automated security." + "teammate": { + "type": "string", + "description": "Teammate's username", + "minLength": 0, + "maxLength": 64, + "pattern": "^$|^[A-Za-z0-9]+" }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." + "api_key_id": { + "type": "string", + "minLength": 3, + "maxLength": 50, + "pattern": "^[A-Za-z0-9]+" }, - "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." - } + "events": { + "type": "array", + "description": "List of events related to email message", + "items": { + "title": "Event", + "type": "object", + "properties": { + "event_name": { + "type": "string", + "description": "Name of event", + "enum": [ + "bounced", + "opened", + "clicked", + "processed", + "dropped", + "delivered", + "deferred", + "spam_report", + "unsubscribe", + "group_unsubscribe", + "group_resubscribe" + ] + }, + "processed": { + "description": "Date of when event occurred", + "minimum": 1292453589, + "maximum": 9999999999, + "type": "string" + }, + "reason": { + "type": "string", + "description": "Explanation of what caused \"bounced\", \"deferred\", or \"blocked\". Usually contains error message from the server - e.g. message from gmail why mail was deferred", + "maxLength": 1024 + }, + "attempt_num": { + "type": "integer", + "description": "Used with \"deferred\" events to indicate the attempt number out of 10. One \"deferred\" entry will exists under events array for each time a message was deferred with error message from the server. ", + "minimum": 1, + "maximum": 10 + }, + "url": { + "type": "string", + "description": "Used with \"clicked\" event to indicate which url the user clicked.", + "pattern": "^((http[s]?|ftp):\\/)?\\/?([^:\\/\\s]+)((\\/\\w+)*\\/)([\\w\\-\\.]+[^#?\\s]+)(.*)?(#[\\w\\-]+)?$" + }, + "bounce_type": { + "type": "string", + "description": "Use to distinguish between types of bounces", + "enum": [ + "bounced", + "blocked", + "expired" + ] + }, + "http_user_agent": { + "type": "string", + "description": "Client recipient used to click or open message" + }, + "mx_server": { + "type": "string", + "description": "For example mx.gmail.com" } }, - "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": [ + "event_name", + "processed", + "url", + "bounce_type", + "http_user_agent", + "mx_server" + ], + "example": { + "event_name": "bounced", + "processed": "2017-10-13T18:56:21Z", + "reason": "some reason", + "url": "http://3LX,MU}N=B8'd,K}>bEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\\!6.1H?$Z9H\"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0\"Q/-4dV\"Yk3QGg[(O86=Pf\"e17K4'r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*O' + description: Text to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %> html: type: string - description: 'HTML to be appended to the email, with the subscription tracking link. You may control where the link is by using the tag <% %>' + description: HTML to be appended to the email with the subscription tracking link. You may control where the link is by using the tag <% %> substitution_tag: type: string - description: 'A tag that will be replaced with the unsubscribe URL. for example: [unsubscribe_url]. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location, with no additional formatting.' + description: 'A tag that will be replaced with the unsubscribe URL. for example: `[unsubscribe_url]`. If this parameter is used, it will override both the `text` and `html` parameters. The URL of the link will be placed at the substitution tag’s location with no additional formatting.' ganalytics: type: object description: Allows you to enable tracking provided by Google Analytics. @@ -308,13 +331,13 @@ paths: description: Name of the marketing medium. (e.g. Email) utm_term: type: string - description: "Used to identify any paid keywords.\t" + description: Used to identify any paid keywords. utm_content: type: string - description: "Used to differentiate your campaign from advertisements.\t" + description: Used to differentiate your campaign from advertisements. utm_campaign: type: string - description: "The name of the campaign.\t" + description: The name of the campaign. required: - personalizations - from @@ -323,484 +346,380 @@ paths: example: personalizations: - to: - - email: john.doe@example.com + - email: john_doe@example.com name: John Doe - subject: 'Hello, World!' + - email: julia_doe@example.com + name: Julia Doe + cc: + - email: jane_doe@example.com + name: Jane Doe + bcc: + - email: james_doe@example.com + name: Jim Doe + - from: + email: sales@example.com + name: Example Sales Team + to: + - email: janice_doe@example.com + name: Janice Doe + bcc: + - email: jordan_doe@example.com + name: Jordan Doe from: - email: sam.smith@example.com - name: Sam Smith + email: orders@example.com + name: Example Order Confirmation reply_to: - email: sam.smith@example.com - name: Sam Smith - subject: 'Hello, World!' + email: customer_service@example.com + name: Example Customer Service Team + subject: Your Example Order Confirmation content: - type: text/html - value: '

Hello, world!

' + value: '

Hello from Twilio SendGrid!

Sending with the email service trusted by developers and marketers for time-savings, scalability, and delivery expertise.

%open-track%

' + attachments: + - content: PCFET0NUWVBFIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KCiAgICA8aGVhZD4KICAgICAgICA8bWV0YSBjaGFyc2V0PSJVVEYtOCI+CiAgICAgICAgPG1ldGEgaHR0cC1lcXVpdj0iWC1VQS1Db21wYXRpYmxlIiBjb250ZW50PSJJRT1lZGdlIj4KICAgICAgICA8bWV0YSBuYW1lPSJ2aWV3cG9ydCIgY29udGVudD0id2lkdGg9ZGV2aWNlLXdpZHRoLCBpbml0aWFsLXNjYWxlPTEuMCI+CiAgICAgICAgPHRpdGxlPkRvY3VtZW50PC90aXRsZT4KICAgIDwvaGVhZD4KCiAgICA8Ym9keT4KCiAgICA8L2JvZHk+Cgo8L2h0bWw+Cg== + filename: index.html + type: text/html + disposition: attachment + categories: + - cake + - pie + - baking + send_at: 1617260400 + batch_id: AsdFgHjklQweRTYuIopzXcVBNm0aSDfGHjklmZcVbNMqWert1znmOP2asDFjkl + asm: + group_id: 12345 + groups_to_display: + - 12345 + ip_pool_name: transactional email + mail_settings: + bypass_list_management: + enable: false + footer: + enable: false + sandbox_mode: + enable: false + tracking_settings: + click_tracking: + enable: true + enable_text: false + open_tracking: + enable: true + substitution_tag: '%open-track%' + subscription_tracking: + enable: false responses: '202': description: '' - schema: - type: 'null' '400': - description: '' - schema: - $ref: '#/definitions/errors' + $ref: '#/responses/trait:mailSendErrors:400' '401': - description: '' - schema: - $ref: '#/definitions/errors' + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' '413': + $ref: '#/responses/trait:mailSendErrors:413' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + /mail/batch: + post: + operationId: POST_mail-batch + summary: Create a batch ID + tags: + - Cancel Scheduled Sends + description: |- + **This endpoint allows you to generate a new batch ID.** + + Once a `batch_id` is created, you can associate it with a scheduled send using the `/mail/send` endpoint. Passing the `batch_id` as a field in the `/mail/send` request body will assign the ID to the send you are creating. + + Once an ID is associated with a scheduled send, the send can be accessed and its send status can be modified using the `batch_id`. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': description: '' schema: - $ref: '#/definitions/errors' + $ref: '#/definitions/mail_batch_id' + examples: + application/json: + batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + '400': + $ref: '#/responses/trait:cancelScheduledSendsErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /alerts: + /user/scheduled_sends: post: - operationId: POST_alerts - summary: Create a new Alert + operationId: POST_user-scheduled_sends + summary: Cancel or pause a scheduled send tags: - - Alerts + - Cancel Scheduled Sends description: |- - **This endpoint allows you to create a new alert.** + **This endpoint allows you to cancel or pause a scheduled send associated with a `batch_id`.** - Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint: + Passing this endpoint a `batch_id` and status will cancel or pause the scheduled send. - * `usage_limit` allows you to set the threshold at which an alert will be sent. - * `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + Once a scheduled send is set to `pause` or `cancel` you must use the "Update a scheduled send" endpoint to change its status or the "Delete a cancellation or pause from a scheduled send" endpoint to remove the status. Passing a status change to a scheduled send that has already been paused or cancelled will result in a `400` level status code. - For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). - consumes: - - application/json - produces: - - application/json + If the maximum number of cancellations/pauses are added to a send, a `400` level status code will be returned. parameters: - name: body in: body schema: + title: Cancel or pause a scheduled send request type: object properties: - type: + batch_id: type: string - description: |- - The type of alert you want to create. Can be either usage_limit or stats_notification. - Example: usage_limit - enum: - - stats_notification - - usage_limit - email_to: - type: - - string - - 'null' - description: |- - The email address the alert will be sent to. - Example: test@example.com - frequency: + description: The batch ID is the identifier that your scheduled mail sends share. + pattern: '^[a-zA-Z0-9]' + status: type: string - description: |- - Required for stats_notification. How frequently the alert will be sent. - Example: daily - percentage: - type: integer - description: |- - Required for usage_alert. When this usage threshold is reached, the alert will be sent. - Example: 90 + 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: - - type - - email_to + - batch_id + - status example: - type: stats_notification - email_to: example@example.com - frequency: daily - - name: Authorization - in: header - type: string - - name: on-behalf-of - in: header - type: string + batch_id: YOUR_BATCH_ID + status: pause + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '201': description: '' schema: - type: object - properties: - created_at: - type: integer - description: A Unix timestamp indicating when the alert was created. - email_to: - type: string - description: The email address that the alert will be sent to. - frequency: - type: string - description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly".' - id: - type: integer - description: The ID of the alert. - type: - type: string - description: The type of alert. - updated_at: - type: integer - description: A Unix timestamp indicating when the alert was last modified. - percentage: - type: integer - description: '"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' - required: - - created_at - - email_to - - id - - type - - updated_at - examples: - application/json: - created_at: 1451520930 - email_to: test@example.com - frequency: daily - id: 48 - type: stats_notification - updated_at: 1451520930 + $ref: '#/definitions/user_scheduled_send_status' '400': - description: '' - schema: - type: object - properties: - field: - type: string - message: - type: string + $ref: '#/responses/trait:cancelScheduledSendsErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] get: - operationId: GET_alerts - summary: Retrieve all alerts + operationId: GET_user-scheduled_sends + summary: Retrieve all scheduled sends tags: - - Alerts + - Cancel Scheduled Sends description: |- - **This endpoint allows you to retieve all of your alerts.** - - Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - * Usage alerts allow you to set the threshold at which an alert will be sent. - * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + **This endpoint allows you to retrieve all cancelled and paused scheduled send information.** - For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). - produces: - - application/json + This endpoint will return only the scheduled sends that are associated with a `batch_id`. If you have scheduled a send using the `/mail/send` endpoint and the `send_at` field but no `batch_id`, the send will be scheduled for delivery; however, it will not be returned by this endpoint. For this reason, you should assign a `batch_id` to any scheduled send you may need to pause or cancel in the future. parameters: - - name: body - in: body - schema: - type: 'null' - - name: Authorization - in: header - type: string - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: type: array - description: The list of alerts. items: - type: object - properties: - created_at: - type: integer - description: A Unix timestamp indicating when the alert was created. - email_to: - type: string - description: The email address that the alert will be sent to. - id: - type: integer - description: The ID of the alert. - percentage: - type: integer - description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' - type: - type: string - description: The type of alert. - enum: - - usage_limit - - stats_notification - updated_at: - type: integer - description: A Unix timestamp indicating when the alert was last modified. - frequency: - type: string - description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly".' - required: - - created_at - - email_to - - id - - type + $ref: '#/definitions/user_scheduled_send_status' examples: application/json: - - created_at: 1451498784 - email_to: example1@example.com - id: 46 - percentage: 90 - type: usage_limit - updated_at: 1451498784 - - created_at: 1451498812 - email_to: example2@example.com - frequency: monthly - id: 47 - type: stats_notification - updated_at: 1451498812 - - created_at: 1451520930 - email_to: example3@example.com - frequency: daily - id: 48 - type: stats_notification - updated_at: 1451520930 + - batch_id: QzZmYzLTVWIwYgYzJlM2NhNWI + status: cancel + - batch_id: mQzZmYzLTVlM2NhNWIwYgYzJl + status: cancel + '400': + $ref: '#/responses/trait:cancelScheduledSendsErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - '/alerts/{alert_id}': + '/mail/batch/{batch_id}': parameters: - - name: alert_id + - name: batch_id in: path - description: The ID of the alert you would like to retrieve. required: true - type: integer + type: string get: - operationId: GET_alerts-alert_id - summary: Retrieve a specific alert + operationId: GET_mail-batch-batch_id + summary: Validate batch ID tags: - - Alerts + - Cancel Scheduled Sends description: |- - **This endpoint allows you to retrieve a specific alert.** + **This endpoint allows you to validate a batch ID.** - Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - * Usage alerts allow you to set the threshold at which an alert will be sent. - * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + When you pass a valid `batch_id` to this endpoint, it will return a `200` status code and the batch ID itself. - For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). - produces: - - application/json + If you pass an invalid `batch_id` to the endpoint, you will receive a `400` level status code and an error message. + + A `batch_id` does not need to be assigned to a scheduled send to be considered valid. A successful response means only that the `batch_id` has been created, but it does not indicate that it has been associated with a send. parameters: - - name: Authorization - in: header - type: string - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - created_at: - type: integer - description: A Unix timestamp indicating when the alert was created. - email_to: - type: string - description: The email address that the alert will be sent to. - frequency: - type: string - description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly".' - id: - type: integer - description: The ID of the alert. - type: - type: string - description: The type of alert. - enum: - - usage_alert - - stats_notification - updated_at: - type: integer - description: A Unix timestamp indicating when the alert was last modified. - percentage: - type: integer - description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' - required: - - created_at - - email_to - - id - - type - - updated_at + $ref: '#/definitions/mail_batch_id' examples: application/json: - created_at: 1451520930 - email_to: example@example.com - frequency: daily - id: 48 - type: stats_notification - updated_at: 1451520930 + batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + '400': + $ref: '#/responses/trait:cancelScheduledSendsErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - delete: - operationId: DELETE_alerts-alert_id - summary: Delete an alert + '/user/scheduled_sends/{batch_id}': + parameters: + - name: batch_id + in: path + required: true + type: string + get: + operationId: GET_user-scheduled_sends-batch_id + summary: Retrieve scheduled send tags: - - Alerts - description: |- - **This endpoint allows you to delete an alert.** - - Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - * Usage alerts allow you to set the threshold at which an alert will be sent. - * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - - For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). + - Cancel Scheduled Sends + description: '**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': + '200': description: '' schema: - type: object - properties: {} + 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 + '400': + $ref: '#/responses/trait:cancelScheduledSendsErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] patch: - operationId: PATCH_alerts-alert_id - summary: Update an alert + operationId: PATCH_user-scheduled_sends-batch_id + summary: Update a scheduled send tags: - - Alerts + - Cancel Scheduled Sends description: |- - **This endpoint allows you to update an alert.** - - Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - * Usage alerts allow you to set the threshold at which an alert will be sent. - * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + **This endpoint allows you to update the status of a scheduled send for the given `batch_id`.** - For more information about alerts, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/alerts.html). - consumes: - - application/json - produces: - - application/json + If you have already set a `cancel` or `pause` status on a scheduled send using the "Cancel or pause a scheduled send" endpoint, you can update it's status using this endpoint. Attempting to update a status once it has been set with the "Cancel or pause a scheduled send" endpoint will result in a `400` error. parameters: - name: body in: body schema: type: object properties: - email_to: - type: string - description: |- - The new email address you want your alert to be sent to. - Example: test@example.com - frequency: + status: type: string - description: |- - The new frequency at which to send the stats_notification alert. - Example: monthly - percentage: - type: integer - description: |- - The new percentage threshold at which the usage_limit alert will be sent. - Example: 90 + description: The status you would like the scheduled send to have. + enum: + - cancel + - pause + required: + - status example: - email_to: example@example.com + status: pause - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' schema: - type: object - properties: - created_at: - type: integer - description: A Unix timestamp indicating when the alert was created. - email_to: - type: string - description: The email address that the alert will be sent to. - frequency: - type: string - description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly".' - id: - type: integer - description: The ID of the alert. - type: - type: string - description: The type of alert. - enum: - - usage_alert - - stats_notification - updated_at: - type: integer - description: A Unix timestamp indicating when the alert was last modified. - percentage: - type: integer - description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' - required: - - created_at - - email_to - - id - - type - - updated_at - examples: - application/json: - created_at: 1451520930 - email_to: example@example.com - frequency: daily - id: 48 - type: stats_notification - updated_at: 1451522691 + type: 'null' + '400': + $ref: '#/responses/trait:cancelScheduledSendsErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /api_keys: - get: - operationId: GET_api_keys - summary: Retrieve all API Keys belonging to the authenticated user + delete: + operationId: DELETE_user-scheduled_sends-batch_id + summary: Delete a cancellation or pause from a scheduled send tags: - - API Keys + - Cancel Scheduled Sends description: |- - **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** + **This endpoint allows you to delete the cancellation/pause of a scheduled send.** - 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). - produces: - - application/json + Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. parameters: - - name: limit - in: query - type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' - schema: - type: object - properties: - result: - type: array - items: - $ref: '#/definitions/api_key_name_id' - examples: - application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id + '400': + $ref: '#/responses/trait:cancelScheduledSendsErrors:400' '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] + /api_keys: post: operationId: create-api-keys summary: Create API keys tags: - API Keys description: |- - **This endpoint allows you to create a new random API Key for the user.** + **This endpoint allows you to create a new 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. + To create your initial SendGrid API Key, you should [use the SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management. - There is a limit of 100 API Keys on your account. + > 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). + A JSON request body containing a `name` property is required when making requests to this endpoint. If the number of maximum keys, 100, is reached, a `403` status will be returned. - 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. - consumes: - - application/json - produces: - - application/json + Though the `name` field is required, it does not need to be unique. A unique API key ID will be generated for each key you create and returned in the response body. + + It is not necessary to pass a `scopes` field to the API when creating a key, but you should be aware that omitting the `scopes` field from your request will create a key with "Full Access" permissions by default. + + See the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the "Update API keys" endpoint. parameters: - name: body in: body @@ -815,8 +734,6 @@ paths: description: The individual permissions that you are giving to this API Key. items: type: string - sample: - type: string required: - name example: @@ -825,7 +742,6 @@ paths: - mail.send - alerts.create - alerts.read - sample: data - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '201': @@ -853,53 +769,34 @@ paths: - alerts.create - alerts.read '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: name - message: missing required argument + $ref: '#/responses/trait:apiKeysErrors:400' '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + $ref: '#/responses/trait:globalErrors:401' '403': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: Cannot create more than 100 API Keys + $ref: '#/responses/trait:apiKeysErrors:403' + '404': + $ref: '#/responses/trait:apiKeysErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - '/api_keys/{api_key_id}': - parameters: - - name: api_key_id - in: path - description: The ID of the API Key for which you are requesting information. - required: true - type: string get: - operationId: GET_api_keys-api_key_id - summary: Retrieve an existing API Key + operationId: GET_api_keys + summary: Retrieve all API Keys belonging to the authenticated user tags: - API Keys description: |- - **This endpoint allows you to retrieve a single api key.** + **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** - If the API Key ID does not exist an HTTP 404 will be returned. - produces: - - application/json + A successful response from this API will include all available API keys' names and IDs. + + For security reasons, there is not a way to retrieve the key itself after it's created. If you lose your API key, you must create a new one. Only the "Create API keys" endpoint will return a key to you and only at the time of creation. + + An `api_key_id` can be used to update or delete the key, as well as retrieve the key's details, such as its scopes. parameters: + - name: limit + in: query + type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': @@ -910,7 +807,7 @@ paths: result: type: array items: - $ref: '#/definitions/api_key_name_id_scopes' + $ref: '#/definitions/api_key_name_id' examples: application/json: result: @@ -919,85 +816,73 @@ paths: - 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 + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' '404': - description: Unexpected error in API call. See HTTP response body for details. - schema: - type: object - examples: - application/json: - errors: - - field: null - message: unable to find API Key + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - delete: - operationId: DELETE_api_keys-api_key_id - summary: Delete API keys + '/api_keys/{api_key_id}': + parameters: + - name: api_key_id + in: path + description: '' + required: true + type: string + get: + operationId: GET_api_keys-api_key_id + summary: Retrieve an existing API Key tags: - API Keys description: |- - **This endpoint allows you to revoke an existing API Key** - - Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. + **This endpoint allows you to retrieve a single API key using an `api_key_id`.** - 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 + The endpoint will return a key's name, ID, and scopes. If the API Key ID does not, exist a `404` status will be returned. - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are deleting.| - produces: - - application/json + See the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. An API key's scopes can be updated after creation using the "Update API keys" endpoint. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': - description: '' - schema: - type: 'null' - examples: - application/json: null - '404': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/api_key_name_id_scopes' examples: application/json: - errors: - - field: null - message: unable to find API Key + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id + '400': + $ref: '#/responses/trait:apiKeysErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:apiKeysErrors:403' + '404': + $ref: '#/responses/trait:apiKeysErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] patch: operationId: PATCH_api_keys-api_key_id - summary: Update API keys + summary: Update API key name tags: - API Keys description: |- **This endpoint allows you to update the name of an existing API Key.** - A JSON request body with a "name" property is required. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters - - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are updating.| - consumes: - - application/json - produces: - - application/json + You must pass this endpoint a JSON request body with a `name` property, which will be used to rename the key associated with the `api_key_id` passed in the URL. parameters: - name: body in: body @@ -1007,6 +892,8 @@ paths: name: type: string description: The new name of the API Key. + required: + - name example: name: A New Hope - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' @@ -1019,33 +906,31 @@ paths: application/json: api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA name: A New Hope + '400': + $ref: '#/responses/trait:apiKeysErrors:400' '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] put: operationId: PUT_api_keys-api_key_id - summary: Update the name & scopes of an API Key + summary: Update API key name and scopes tags: - API Keys description: |- **This endpoint allows you to update the name and scopes of a given API key.** - A JSON request body with a "name" property is required. - Most provide the list of all the scopes an api key should have. + You must pass this endpoint a JSON request body with a `name` field and a `scopes` array containing at least one scope. The `name` and `scopes` fields will be used to update the key associated with the `api_key_id` in the request URL. - 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). - consumes: - - application/json - produces: - - application/json + If you need to update a key's scopes only, pass the `name` field with the key's existing name; the `name` will not be modified. If you need to update a key's name only, use the "Update API key name" endpoint. + + See the [API Key Permissions List](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization) for all available scopes. parameters: - name: body in: body @@ -1058,8 +943,10 @@ paths: type: array items: type: string + required: + - name example: - name: A New Hope + name: Profiles key scopes: - user.profile.read - user.profile.update @@ -1072,258 +959,87 @@ paths: examples: application/json: api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope + name: Profiles Key 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 + $ref: '#/responses/trait:apiKeysErrors:400' '401': - description: '' - schema: - type: object + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' '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 + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /suppression/blocks: - get: - operationId: GET_suppression-blocks - summary: Retrieve all blocks + delete: + operationId: DELETE_api_keys-api_key_id + summary: Delete API keys tags: - - Blocks API + - API Keys description: |- - **This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.** + **This endpoint allows you to revoke an existing API Key using an `api_key_id`** - There are several causes for [blocked](https://sendgrid.com/docs/Glossary/blocks.html) emails: for example, your mail server IP address is on an ISP blacklist, or blocked by an ISP, or if the receiving server flags the message content. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - produces: - - application/json + Authentications using a revoked API Key will fail after after some small propogation delay. If the API Key ID does not exist, a `404` status will be returned. parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when a blocked email was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when a blocked email was created (inclusive). - type: integer - - name: limit - in: query - description: Limit the number of results to be displayed per page. - type: integer - - name: offset - in: query - description: The point in the list to begin displaying results. - type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' - schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the blocks list. - email: - type: string - description: The email address that was added to the block list. - reason: - type: string - description: An explanation for the reason of the block. - status: - type: string - description: The status of the block. - required: - - created - - email - - reason - - status - examples: - application/json: - - created: 1443651154 - email: example@example.com - reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' - status: 4.0.0 + '400': + $ref: '#/responses/trait:apiKeysErrors:400' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - delete: - operationId: DELETE_suppression-blocks - summary: Delete blocks + /scopes: + get: + operationId: GET_scopes + summary: Retrieve a list of scopes for which this user has access. tags: - - Blocks API + - API Key Permissions description: |- - **This endpoint allows you to delete all email addresses on your blocks list.** + **This endpoint returns a list of all scopes that this user has access to.** - There are two options for deleting blocked emails: + API Keys are used to authenticate with [SendGrid's v3 API](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization). - 1. You can delete all blocked emails by setting `delete_all` to true in the request body. - 2. You can delete some blocked emails by specifying the email addresses in an array in the request body. + API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + This endpoint returns all the scopes assigned to the key you use to authenticate with it. To retrieve the scopes assigned to another key, you can pass an API key ID to the "Retrieve an existing API key" endpoint. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - produces: - - application/json + For a more detailed explanation of how you can use API Key permissions, please visit our [API Keys documentation](https://sendgrid.com/docs/ui/account-and-settings/api-keys/). parameters: - - name: body - in: body + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' schema: type: object properties: - delete_all: - type: boolean - description: Indicates if you want to delete all blocked email addresses. - emails: + scopes: type: array - description: The specific blocked email addresses that you want to delete. + description: The list of scopes for which this user has access. + uniqueItems: true items: type: string - example: - delete_all: false - emails: - - example1@example.com - - example2@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - '/suppression/blocks/{email}': - parameters: - - name: email - in: path - description: The email address of the specific block. - required: true - type: string - get: - operationId: GET_suppression-blocks-email - summary: Retrieve a specific block - tags: - - Blocks API - description: |- - **This endpoint allows you to retrieve a specific email address from your blocks list.** - - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the block was created. - email: - type: string - description: The email address of the recipient that was blocked. - reason: - type: string - description: The reason why the email was blocked. - status: - type: string - description: The status of the block. - required: - - created - - email - - reason - examples: - application/json: - - created: 1443651154 - email: example@example.com - reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' - status: 4.0.0 - security: - - Authorization: [] - delete: - operationId: DELETE_suppression-blocks-email - summary: Delete a specific block - tags: - - Blocks API - description: |- - **This endpoint allows you to delete a specific email address from your blocks list.** - - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:authorizationHeader:Authorization' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - properties: {} - /scopes: - get: - operationId: GET_scopes - summary: Retrieve a list of scopes for which this user has access. - tags: - - API Key Permissions - description: |- - **This endpoint returns a list of all scopes that this user has access to.** - - API Keys can be used to authenticate the use of [SendGrid’s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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': + required: + - scopes + examples: + application/json: + scopes: + - mail.send + - alerts.create + - alerts.read + '401': description: '' schema: type: object @@ -1349,376 +1065,250 @@ paths: errors: - field: null message: authorization required + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /suppression/bounces: + /user/settings/enforced_tls: get: - operationId: GET_suppression-bounces - summary: Retrieve all bounces + operationId: GET_user-settings-enforced_tls + summary: Retrieve current Enforced TLS settings. tags: - - Bounces API + - Settings - Enforced TLS description: |- - **This endpoint allows you to retrieve all of your bounces.** - - A bounced email is when the message is undeliverable and then returned to the server that sent it. + **This endpoint allows you to retrieve your current Enforced TLS settings.** - For more information see: + The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - produces: - - application/json + If either `require_tls` or `require_valid_cert` is set to `true`, the recipient must support TLS 1.1 or higher or have a valid certificate. If these conditions are not met, Twilio SendGrid will drop the message and send a block event with “TLS required but not supported” as the description. parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). - type: integer - - name: Accept - in: header - required: true - type: string - default: application/json - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: number - email: - type: string - reason: - type: string - status: - type: string + $ref: '#/definitions/enforced-tls-request-response' 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 + require_tls: false + require_valid_cert: false '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + patch: + operationId: PATCH_user-settings-enforced_tls + summary: Update Enforced TLS settings + tags: + - Settings - Enforced TLS + description: |- + **This endpoint allows you to update your Enforced TLS settings.** + + To require TLS from recipients, set `require_tls` to `true`. If either `require_tls` or `require_valid_cert` is set to `true`, the recipient must support TLS 1.1 or higher or have a valid certificate. If these conditions are not met, Twilio SendGrid will drop the message and send a block event with “TLS required but not supported” as the description. + + > Twilio SendGrid supports TLS 1.1 and higher and does not support older versions of TLS due to security vulnerabilities. + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/enforced-tls-request-response' + example: + require_tls: true + require_valid_cert: false + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/enforced-tls-request-response' examples: application/json: - errors: - - field: null - message: authorization required + require_tls: true + require_valid_cert: false + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - delete: - operationId: DELETE_suppression-bounces - summary: Delete bounces + /access_settings/whitelist: + post: + operationId: POST_access_settings-whitelist + summary: Add one or more IPs to the allow list tags: - - Bounces API + - IP Access Management description: |- - **This endpoint allows you to delete all of your bounces. You can also use this endpoint to remove a specific email address from your bounce list.** - - A bounced email is when the message is undeliverable and then returned to the server that sent it. - - For more information see: - - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) + **This endpoint allows you to add one or more allowed IP addresses.** - Note: the `delete_all` and `emails` parameters should be used independently of each other as they have different purposes. - consumes: - - application/json - produces: - - application/json + To allow one or more IP addresses, pass them to this endpoint in an array. Once an IP address is added to your allow list, it will be assigned an `id` that can be used to remove the address. You can retrieve the ID associated with an IP using the "#endpoint:nzCz472S9yaNpgmDu" endpoint. 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: + ips: type: array - description: Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter. + description: An array containing the IP(s) you want to allow. items: - type: string + type: object + properties: + ip: + type: string + description: An IP address that you want to allow. + required: + - ip + required: + - ips example: - delete_all: true - emails: - - example@example.com - - example2@example.com + ips: + - ip: 192.168.1.1 + - ip: 192.*.*.* + - ip: 192.168.1.3/32 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': - description: '' - schema: - type: 'null' - '401': + '201': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/ip-access-response' examples: application/json: - errors: - - field: null - message: authorization required + result: + - id: 1 + ip: 192.168.1.1/32 + created_at: 1441824715 + updated_at: 1441824715 + - id: 2 + ip: 192.0.0.0/8 + created_at: 1441824715 + updated_at: 1441824715 + - id: 3 + ip: 192.168.1.3/32 + created_at: 1441824715 + updated_at: 1441824715 + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - '/suppression/bounces/{email}': - parameters: - - name: email - in: path - required: true - type: string get: - operationId: GET_suppression-bounces-email - summary: Retrieve a Bounce + operationId: GET_access_settings-whitelist + summary: Retrieve a list of currently allowed IPs tags: - - Bounces API + - IP Access Management description: |- - **This endpoint allows you to retrieve a specific bounce for a given email address.** - - A bounced email is when the message is undeliverable and then returned to the server that sent it. - - For more information see: + **This endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account.** - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) - produces: - - application/json + Each IP address returned to you will have `created_at` and `updated_at` dates. Each IP will also be associated with an `id` that can be used to remove the address from your allow list. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - email: - type: string - reason: - type: string - status: - type: string + $ref: '#/definitions/ip-access-response' examples: application/json: - - created: 1443651125 - email: bounce1@test.com - reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ' - status: 5.1.1 - security: + result: + - id: 1 + ip: 192.168.1.1/32 + created_at: 1441824715 + updated_at: 1441824715 + - id: 2 + ip: 192.168.1.2/32 + created_at: 1441824715 + updated_at: 1441824715 + - id: 3 + ip: 192.168.1.3/32 + created_at: 1441824715 + updated_at: 1441824715 + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: - Authorization: [] delete: - operationId: DELETE_suppression-bounces-email - summary: Delete a bounce + operationId: DELETE_access_settings-whitelist + summary: Remove one or more IPs from the allow list tags: - - Bounces API + - IP Access Management description: |- - **This endpoint allows you to remove an email address from your bounce list.** - - A bounced email is when the message is undeliverable and then returned to the server that sent it. This endpoint allows you to delete a single email addresses from your bounce list. + **This endpoint allows you to remove one or more IP addresses from your list of allowed addresses.** - For more information see: + To remove one or more IP addresses, pass this endpoint an array containing the ID(s) associated with the IP(s) you intend to remove. You can retrieve the IDs associated with your allowed IP addresses using the "#endpoint:nzCz472S9yaNpgmDu" endpoint. - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) - produces: - - application/json + It is possible to remove your own IP address, which will block access to your account. You will need to submit a [support ticket](https://sendgrid.com/docs/ui/account-and-settings/support/) if this happens. For this reason, it is important to double check that you are removing only the IPs you intend to remove when using this endpoint. parameters: - - name: email_address - in: query - description: The email address you would like to remove from the bounce list. - required: true - type: string - format: email - name: body in: body schema: - type: 'null' + type: object + properties: + ids: + type: array + description: An array of the IDs of the IP address that you want to remove from your allow list. + items: + type: integer + example: + ids: + - 1 + - 2 + - 3 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '204': description: '' schema: type: object + properties: {} '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - /campaigns: - post: - operationId: POST_campaigns - summary: Create a Campaign - tags: - - Campaigns API - description: |- - **This endpoint allows you to create a campaign.** - - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/campaign_request' - example: - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:

Check out our spring line!

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

Check out our spring line!

- plain_content: Check out our spring line! - status: Draft - '400': - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: title - message: title can't be blank - - field: title - message: title is too long (maximum is 100 characters) - - field: categories - message: categories exceeds 10 category limit - - field: html_content - message: html_content exceeds the 1MB limit - - field: plain_content - message: plain_content exceeds the 1MB limit - - field: sender_id - message: sender_id does not exist - - field: sender_id - message: sender_id is not a verified sender identity - - field: list_ids - message: list_ids do not all exist - - field: segment_ids - message: segment_ids do not all exist - - field: ip_pool - message: The ip pool you provided is invalid - - field: suppression_group_id - message: suppression_group_id does not exist - - field: unsubscribes - message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: You've reached your limit of 250 campaigns. Please delete one or more and try again. - '401': - description: '' - schema: - type: object + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] + /access_settings/activity: get: - operationId: GET_campaigns - summary: Retrieve all Campaigns + operationId: GET_access_settings-activity + summary: Retrieve all recent access attempts tags: - - Campaigns API - description: |- - **This endpoint allows you to retrieve a list of all of your campaigns.** - - Returns campaigns in reverse order they were created (newest first). - - Returns an empty array if no campaigns exist. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - produces: - - application/json + - IP Access Management + description: '**This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.**' parameters: - name: limit in: query - description: The number of results you would like to receive at a time. - type: integer - default: 10 - - name: offset - in: query - description: 'The index of the first campaign to return, where 0 is the first campaign.' + description: Limits the number of IPs to return. type: integer - default: 0 + default: 20 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' @@ -1727,1220 +1317,1456 @@ paths: properties: result: type: array + description: An array containing the IPs that recently attempted to access your account. items: type: object properties: - categories: - type: array - items: - type: string - custom_unsubscribe_url: - type: string - html_content: - type: string - id: - type: integer - ip_pool: - type: string - list_ids: - type: array - items: - type: integer - plain_content: + allowed: + type: boolean + description: Indicates if the IP address was granted access to the account. + auth_method: type: string - segment_ids: - type: array - items: - type: integer - sender_id: + description: The authentication method used when attempting access. + first_at: type: integer - status: - type: string - subject: + description: A Unix timestamp indicating when the first access attempt was made. + ip: type: string - suppression_group_id: + description: The IP addressed used during the access attempt. + last_at: type: integer - title: + description: A Unix timestamp indicating when the most recent access attempt was made + location: type: string + description: The geographic location from which the access attempt originated. + required: + - allowed + - auth_method + - first_at + - ip + - last_at + - location + required: + - result examples: application/json: result: - - categories: - - spring line - custom_unsubscribe_url: '' - html_content:

Check out our spring line!

- id: 986724 - ip_pool: marketing - list_ids: - - 110 - plain_content: Check out our spring line! - segment_ids: - - 110 - sender_id: 124451 - status: Draft - subject: New Products for Spring! - suppression_group_id: 42 - title: March Newsletter + - allowed: false + auth_method: Web + first_at: 1444087966 + ip: 1.1.1.1 + last_at: 1444406672 + location: Australia + - allowed: false + auth_method: Web + first_at: 1444087505 + ip: 1.2.3.48 + last_at: 1444087505 + location: 'Mukilteo, Washington' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - '/campaigns/{campaign_id}': + '/access_settings/whitelist/{rule_id}': parameters: - - name: campaign_id + - name: rule_id in: path - description: The id of the campaign you would like to retrieve. + description: The ID of the allowed IP address that you want to retrieve. required: true - type: integer + type: string get: - operationId: GET_campaigns-campaign_id - summary: Retrieve a single campaign + operationId: GET_access_settings-whitelist-rule_id + summary: Retrieve a specific allowed IP tags: - - Campaigns API + - IP Access Management description: |- - **This endpoint allows you to retrieve a specific campaign.** + **This endpoint allows you to retreive a specific IP address that has been allowed to access your account.** - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - produces: - - application/json + You must include the ID for the specific IP address you want to retrieve in your call. You can retrieve the IDs associated with your allowed IP addresses using the "#endpoint:nzCz472S9yaNpgmDu" endpoint. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - categories: - type: array - items: - type: string - custom_unsubscribe_url: - type: string - html_content: - type: string - id: - type: integer - ip_pool: - type: string - list_ids: - type: array - items: - type: integer - plain_content: - type: string - segment_ids: - type: array - items: - type: integer - sender_id: - type: integer - status: - type: string - subject: - type: string - suppression_group_id: - type: integer - title: - type: string - examples: - application/json: - categories: - - spring line - custom_unsubscribe_url: '' - html_content:

Check out our spring line!

- id: 986724 - ip_pool: marketing - list_ids: - - 110 - plain_content: Check out our spring line! - segment_ids: - - 110 - sender_id: 124451 - status: Draft - subject: New Products for Spring! - suppression_group_id: 42 - title: March Newsletter - '401': - description: '' - schema: - type: object - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"": "not found"' - schema: - type: object + $ref: '#/definitions/ip-access-response' examples: application/json: - errors: - - field: null - message: not found + id: 1 + ip: 192.168.1.1 + created_at: 1441824715 + updated_at: 1441824715 security: - Authorization: [] delete: - operationId: DELETE_campaigns-campaign_id - summary: Delete a Campaign + operationId: DELETE_access_settings-whitelist-rule_id + summary: Remove a specific IP from the allowed list tags: - - Campaigns API + - IP Access Management description: |- - **This endpoint allows you to delete a specific campaign.** + **This endpoint allows you to remove a specific IP address from your list of allowed addresses.** - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - produces: - - application/json + When removing a specific IP address from your list, you must include the ID in your call. You can retrieve the IDs associated with your allowed IP addresses using the "#endpoint:nzCz472S9yaNpgmDu" endpoint. parameters: - - name: body - in: body - schema: - type: 'null' + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '204': description: '' - schema: - type: 'null' - '401': - description: '' - schema: - type: object - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"": "not found"' schema: type: object + properties: {} security: - Authorization: [] - patch: - operationId: PATCH_campaigns-campaign_id - summary: Update a Campaign + /sso/certificates: + post: + operationId: POST_sso-certificates + summary: Create an SSO Certificate tags: - - Campaigns API - 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) - consumes: - - application/json - produces: - - application/json + - Certificates + description: '**This endpoint allows you to create an SSO certificate.**' parameters: - name: body in: body schema: - title: Update a Campaign request type: object + description: '' 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: + public_certificate: type: string - description: The HTML content of this campaign. - plain_content: + description: This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes. + enabled: + type: boolean + description: Indicates if the certificate is enabled. + integration_id: type: string - description: The plain content of this campaign. + description: An ID that matches a certificate to a specific IdP integration. This is the `id` returned by the "Get All SSO Integrations" endpoint. required: - - title - - subject - - categories - - html_content - - plain_content + - public_certificate + - integration_id 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! + public_certificate: + enabled: false + integration_id: b0b98502-9408-4b24-9e3d-31ed7cb15312 responses: '200': description: '' schema: - $ref: '#/definitions/campaign_response' + $ref: '#/definitions/sso-certificate-body' 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 + public_certificate: + id: 66138975 + not_before: 1621289880 + not_after: 1621289880 + intergration_id: b0b98502-9408-4b24-9e3d-31ed7cb15312 '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." + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + '/sso/integrations/{integration_id}/certificates': + parameters: + - name: integration_id + in: path + description: An ID that matches a certificate to a specific IdP integration. + required: true + type: string + get: + operationId: GET_sso-integrations-integration_id-certificates + summary: Get All SSO Certificates by Integration + tags: + - Certificates + description: |- + **This endpoint allows you to retrieve all your IdP configurations by configuration ID.** + + The `integration_id` expected by this endpoint is the `id` returned in the response by the #endpoint:qv7RWLGAHninr8zdG endpoint. + responses: + '200': + description: '' schema: - type: object + type: array + items: + $ref: '#/definitions/sso-certificate-body' 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. + - public_certificate: + id: 66138975 + not_before: 1621289880 + not_after: 1621289880 + intergration_id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + '/sso/certificates/{cert_id}': + parameters: + - name: cert_id + in: path + required: true + type: string + get: + operationId: GET_sso-certificates-cert_id + summary: Get an SSO Certificate + tags: + - Certificates + description: '**This endpoint allows you to retrieve an individual SSO certificate.**' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/sso-certificate-body' examples: application/json: - errors: - - field: null - message: authorization required + public_certificate: + id: 66138975 + not_before: 1621289880 + not_after: 1621289880 + intergration_id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' '403': - description: '"": "You may only update a campaign when it is in draft mode."' + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + patch: + operationId: PATCH_sso-certificates-cert_id + summary: Update SSO Certificate + tags: + - Certificates + description: |- + **This endpoint allows you to update an existing certificate by ID.** + + You can retrieve a certificate's ID from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint. + parameters: + - name: body + in: body schema: type: object - examples: - application/json: - errors: - - field: null - message: You may only update a campaign when it is in draft mode. - '404': - description: '"": "not found"' + properties: + public_certificate: + type: string + description: This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes. + enabled: + type: boolean + description: Indicates whether or not the certificate is enabled. + integration_id: + type: string + description: An ID that matches a certificate to a specific IdP integration. + example: + public_certificate: + enabled: false + intergration_id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + responses: + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + delete: + operationId: DELETE_sso-certificates-cert_id + summary: Delete an SSO Certificate + tags: + - Certificates + description: |- + **This endpoint allows you to delete an SSO certificate.** + + You can retrieve a certificate's ID from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint. + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/sso-certificate-body' examples: application/json: - errors: - - field: null - message: not found - security: - - Authorization: [] - '/campaigns/{campaign_id}/schedules/now': - parameters: - - name: campaign_id - in: path - required: true - type: integer + public_certificate: + id: 66138975 + not_before: 1621289880 + not_after: 1621289880 + intergration_id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + /sso/integrations: post: - operationId: POST_campaigns-campaign_id-schedules-now - summary: Send a Campaign + operationId: POST_sso-integrations + summary: Create an SSO Integration tags: - - Campaigns API - description: |- - **This endpoint allows you to immediately send a campaign at the time you make the API call.** - - Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - produces: - - application/json + - Single Sign-On Settings + description: '**This endpoint allows you to create an SSO integration.**' parameters: - name: body in: body schema: - type: 'null' + $ref: '#/definitions/create-integration-request' + example: + name: Twilio SendGrid + enabled: true + signin_url: 'https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6' + signout_url: 'https://example.okta.com/login/signout?fromURI=exampleappurl' + entity_id: 'http://www.okta.com/${org.externalKey}' + completed_integration: true + id: b0b98502-9408-4b24-9e3d-31ed7cb15312 responses: - '201': + '200': description: '' schema: - title: Send a Campaign response - type: object - properties: - id: - type: integer - format: int64 - status: - type: string - required: - - id - - status + $ref: '#/definitions/sso-integration' examples: application/json: - id: 1234 - status: Scheduled + name: Twilio SendGrid + enabled: true + signin_url: 'https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6' + signout_url: 'https://example.okta.com/login/signout?fromURI=exampleappurl' + entity_id: 'http://www.okta.com/${org.externalKey}' + last_updated: 1621288964 '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" + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + get: + operationId: GET_sso-integrations + summary: Get All SSO Integrations + tags: + - Single Sign-On Settings + description: |- + **This endpoint allows you to retrieve all SSO integrations tied to your Twilio SendGrid account.** + + The IDs returned by this endpoint can be used by the APIs additional endpoints to modify your SSO integrations. + parameters: + - name: si + in: query + description: 'If this parameter is set to `true`, the response will include the `completed_integration` field.' + type: boolean + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: subject - message: subject can't be blank - - field: sender_id - message: sender_id can't be blank - - field: plain_content - message: 'plain_content can''t be blank, please provide plain text or html content' - - field: list_id - message: You must select at least 1 segment or 1 list to send to. - - field: unsubscribe_tag - message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' - - field: suppression_group_id - message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + type: array + items: + $ref: '#/definitions/sso-integration' + examples: + application/json: + - name: Twilio SendGrid + enabled: true + signin_url: 'https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6' + signout_url: 'https://example.okta.com/login/signout?fromURI=exampleappurl' + entity_id: 'http://www.okta.com/${org.externalKey}' + last_updated: 1621288520 + completed_integration: true + id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + single_signon_url: 'https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312' + audience_url: 'https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312' + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + '/sso/integrations/{id}': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: GET_sso-integrations-id + summary: Get an SSO Integration + tags: + - Single Sign-On Settings + description: |- + **This endpoint allows you to retrieve an SSO integration by ID.** + + You can retrieve the IDs for your configurations from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint. + parameters: + - name: si + in: query + description: 'If this parameter is set to `true`, the response will include the `completed_integration` field.' + type: boolean + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/sso-integration' examples: application/json: - errors: - - field: null - message: authorization required + name: Twilio SendGrid + enabled: true + signin_url: 'https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6' + signout_url: 'https://example.okta.com/login/signout?fromURI=exampleappurl' + entity_id: 'http://www.okta.com/${org.externalKey}' + last_updated: 1621288964 + completed_integration: true + id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + audience_url: 'https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312' + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' '403': - description: '"": "You may only send a campaign when it is in draft mode."' + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + patch: + operationId: PATCH_sso-integrations-id + summary: Update an SSO Integration + tags: + - Single Sign-On Settings + description: |- + **This endpoint allows you to modify an exisiting SSO integration.** + + You can retrieve the IDs for your configurations from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint. + parameters: + - name: si + in: query + description: 'If this parameter is set to `true`, the response will include the `completed_integration` field.' + type: boolean + - name: body + in: body + schema: + $ref: '#/definitions/create-integration-request' + example: + name: Twilio SendGrid + enabled: true + signin_url: 'https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6' + signout_url: 'https://example.okta.com/login/signout?fromURI=exampleappurl' + entity_id: 'http://www.okta.com/${org.externalKey}' + last_updated: 1621288964 + completed_integration: true + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/sso-integration' examples: application/json: - errors: - - field: null - message: You may only send a campaign when it is in draft mode. - '404': - description: '"": "not found"' + name: Twilio SendGrid + enabled: true + signin_url: 'https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6' + signout_url: 'https://example.okta.com/login/signout?fromURI=exampleappurl' + entity_id: 'http://www.okta.com/${org.externalKey}' + last_updated: 1621288964 + id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + single_signon_url: 'https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312' + audience_url: 'https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312' + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + delete: + operationId: DELETE_sso-integrations-id + summary: Delete an SSO Integration + tags: + - Single Sign-On Settings + description: |- + **This endpoint allows you to delete an IdP configuration by ID.** + + You can retrieve the IDs for your configurations from the response provided by the #endpoint:qv7RWLGAHninr8zdG endpoint. + responses: + '204': + description: '' + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + /sso/teammates: + post: + operationId: POST_sso-teammates + summary: Create SSO Teammate + tags: + - Single Sign-On Teammates + description: |- + **This endpoint allows you to create an SSO Teammate.** + + The email provided for this user will also function as the Teammate’s username. + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/sso-teammate-request' + example: + first_name: Jane + last_name: Doe + email: jane_doe@example.com + scopes: + - mail.batch.create + - mail.batch.delete + - mail.batch.read + - mail.batch.update + - mail.send + responses: + '201': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/sso-teammate-response' examples: application/json: - errors: - - field: null - message: not found - security: - - Authorization: [] - '/campaigns/{campaign_id}/schedules': + first_name: Jane + last_name: Doe + email: jane_doe@example.com + is_read_only: true + username: jane_doe@example.com + is_sso: true + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' + '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + '/sso/teammates/{username}': parameters: - - name: campaign_id + - name: username in: path + description: This email address must be the same address assigned to the teammate in your IdP required: true - type: integer - post: - operationId: POST_campaigns-campaign_id-schedules - summary: Schedule a Campaign + type: string + format: email + patch: + operationId: PATCH_sso-teammates-username + summary: Edit an SSO Teammate tags: - - Campaigns API + - Single Sign-On Teammates description: |- - **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** + **This endpoint allows you to modify an existing SSO Teammate.** - For more information: + To turn a teammate into an admin, the request body should contain the `is_admin` field set to `true`. Otherwise, set `is_admin` to false and pass in all the scopes that a teammate should have. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - consumes: - - application/json - produces: - - application/json + Only the parent user and Teammates with admin permissions can update another Teammate’s permissions. Admin users can only update permissions. 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 + first_name: + type: string + last_name: + type: string + scopes: + type: array + items: + type: string + is_admin: + type: boolean example: - send_at: 1489771528 + first_name: Jane + last_name: Doe + email: jane_doe@example.com + scopes: + - mail.batch.create + - mail.batch.delete + - mail.batch.read + - mail.batch.update + - mail.send + is_admin: false responses: - '201': + '200': description: '' schema: - title: Schedule a Campaign response - type: object - properties: - id: - type: integer - description: The campaign ID. - send_at: - type: integer - description: The date time you scheduled your campaign to be sent. - status: - type: string - description: The status of your campaign. - enum: - - Scheduled - required: - - id - - send_at - - status + $ref: '#/definitions/sso-teammates-patch-response' examples: application/json: - id: 1234 - send_at: 1489771528 - status: Scheduled - '400': - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "send_at": "Please choose a future time for sending your campaign." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "The JSON you have submitted cannot be parsed." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: subject - message: subject can't be blank - - field: sender_id - message: sender_id can't be blank - - field: plain_content - message: 'plain_content can''t be blank, please provide plain text or html content' - - field: list_id - message: You must select at least 1 segment or 1 list to send to. - - field: unsubscribe_tag - message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' - - field: suppression_group_id - message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + first_name: Jane + last_name: Doe + email: jane_doe@example.com + is_admin: false + username: jane_doe@example.com + is_sso: true + address: 1234 Fake St. + address2: Suite 5 + city: San Francisco + state: CA + zip: '94105' + Country: United States + phone: '+15555555555' + user_type: teammate + '400': + $ref: '#/responses/trait:singleSignOnErrorsTrait:400' '401': + $ref: '#/responses/trait:singleSignOnErrorsTrait:401' + '403': + $ref: '#/responses/trait:singleSignOnErrorsTrait:403' + '429': + $ref: '#/responses/trait:singleSignOnErrorsTrait:429' + '500': + $ref: '#/responses/trait:singleSignOnErrorsTrait:500' + /mail_settings: + get: + operationId: GET_mail_settings + summary: Retrieve all mail settings + tags: + - Settings - Mail + description: |- + **This endpoint allows you to retrieve a list of all mail settings.** + + Each setting will be returned with an `enabled` status set to `true` or `false` and a short description that explains what the setting does. + 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 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + 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: - errors: - - field: null - message: authorization required + result: + - title: Address Whitelist + enabled: false + name: address_whitelist + description: Address / domains that should never have email suppressed. + - 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. + '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' '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. + $ref: '#/responses/trait:makoErrorResponse:403' '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] + /mail_settings/address_whitelist: patch: - operationId: PATCH_campaigns-campaign_id-schedules - summary: Update a Scheduled Campaign + operationId: PATCH_mail_settings-address_whitelist + summary: Update address whitelist mail settings tags: - - Campaigns API + - Settings - Mail description: |- - **This endpoint allows to you change the scheduled time and date for a campaign to be sent.** + **This endpoint allows you to update your current email address whitelist settings.** - For more information: + You can select whether or not this setting should be enabled by assigning the `enabled` field a `true` or `false` value. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - consumes: - - application/json - produces: - - application/json + Passing only the `enabled` field to this endpoint will not alter your current `list` of whitelist entries. However, any modifications to your `list` of entries will overwrite the entire list. For this reason, you must included all existing entries you wish to retain in your `list` in addition to any new entries you intend to add. To remove one or more `list` entries, pass a `list` with only the entries you wish to retain. + + You should not add generic domains such as `gmail.com` or `yahoo.com` in your `list` because your emails will not honor recipients' unsubscribes. This may cause a legal violation of [CAN-SPAM](https://sendgrid.com/docs/glossary/can-spam/) and could damage your sending reputation. + + The Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed. + + For example, if you own the domain `example.com`, and one or more of your recipients use `email@example.com` addresses, placing `example.com` in the address whitelist setting instructs Twilio SendGrid to ignore all bounces, blocks, and unsubscribes logged for that domain. In other words, all bounces, blocks, and unsubscribes will still be sent to `example.com` as if they were sent under normal sending conditions. parameters: - name: body in: body schema: - title: Update a Scheduled Campaign request type: object properties: - send_at: - type: integer - format: int64 - required: - - send_at + enabled: + type: boolean + description: Indicates if your email address whitelist is enabled. + list: + type: array + description: 'Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.' + items: + type: string example: - send_at: 1489451436 + enabled: true + list: + - email1@example.com + - example.com + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - title: Update a Scheduled Campaign response - type: object - properties: - id: - type: integer - description: The campaign ID - send_at: - type: integer - description: The unix timestamp to send the campaign. - status: - type: string - description: The status of the schedule. - required: - - id - - send_at - - status - '400': - description: |- - "": "The JSON you have submitted cannot be parsed." - "send_at": "Please choose a future time for sending your campaign." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_address_whitelabel' 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' + enabled: true + list: + - email1@example.com + '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' '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. + $ref: '#/responses/trait:makoErrorResponse:403' '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] get: - operationId: GET_campaigns-campaign_id-schedules - summary: View Scheduled Time of a Campaign + operationId: GET_mail_settings-address_whitelist + summary: Retrieve address whitelist mail settings tags: - - Campaigns API + - Settings - Mail description: |- - **This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.** + **This endpoint allows you to retrieve your current email address whitelist settings.** - For more information: + The Address Whitelist setting allows you to specify email addresses or domains for which mail should never be suppressed. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - produces: - - application/json + For example, if you own the domain `example.com`, and one or more of your recipients use `email@example.com` addresses, placing `example.com` in the address whitelist setting instructs Twilio SendGrid to ignore all bounces, blocks, and unsubscribes logged for that domain. In other words, all bounces, blocks, and unsubscribes will still be sent to `example.com` as if they were sent under normal sending conditions. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - title: View Scheduled Time of a Campaign response - type: object - properties: - send_at: - type: integer - format: int64 - required: - - send_at + $ref: '#/definitions/mail_settings_address_whitelabel' examples: application/json: - send_at: 1490778528 + enabled: true + list: + - example.com + - jane_doe@example1.com + '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] - delete: - operationId: DELETE_campaigns-campaign_id-schedules - summary: Unschedule a Scheduled Campaign + /mail_settings/footer: + patch: + operationId: PATCH_mail_settings-footer + summary: Update footer mail settings tags: - - Campaigns API + - Settings - Mail description: |- - **This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.** - - A successful unschedule will return a 204. - If the specified campaign is in the process of being sent, the only option is to cancel (a different method). + **This endpoint allows you to update your current Footer mail settings.** - For more information: + The Footer setting will insert a custom footer at the bottom of your text and HTML email message bodies. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - produces: - - application/json + You can insert your HTML or plain text directly using this endpoint, or you can create the footer using the [Mail Settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). parameters: - name: body in: body schema: - type: 'null' + $ref: '#/definitions/mail_settings_footer' + example: + enabled: true + html_content: | +

Ahoy, World!

+ plain_content: '' + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': + '200': description: '' schema: - type: 'null' - '403': - description: |- - "": "This campaign is already In Progress." - "": "This campaign is already Sent." - "": "This campaign is already Paused." - "": "This campaign is already Canceled." - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_footer' 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. + enabled: true + html_content: | +

Ahoy, World!

+ plain_content: '' + '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] - '/campaigns/{campaign_id}/schedules/test': - parameters: - - name: campaign_id - in: path - required: true - type: integer - post: - operationId: POST_campaigns-campaign_id-schedules-test - summary: Send a Test Campaign + get: + operationId: GET_mail_settings-footer + summary: Retrieve footer mail settings tags: - - Campaigns API + - Settings - Mail description: |- - **This endpoint allows you to send a test campaign.** - - To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] + **This endpoint allows you to retrieve your current Footer mail settings.** - For more information: + The Footer setting will insert a custom footer at the bottom of your text and HTML email message bodies. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - consumes: - - application/json - produces: - - application/json + You can insert your HTML or plain text directly using the #endpoint:LPTaj7czYsMS8spND, or you can create the footer using the [Mail Settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). 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 - example: - to: your.email@example.com + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': + '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_footer' 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' + enabled: true + html_content: | +

Ahoy, World!

+ plain_content: '' + '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] - /mail/batch: - post: - operationId: POST_mail-batch - summary: Create a batch ID + /mail_settings/forward_spam: + patch: + operationId: PATCH_mail_settings-forward_spam + summary: Update forward spam mail settings tags: - - Cancel Scheduled Sends + - Settings - Mail description: |- - **This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.** + **This endpoint allows you to update your current Forward Spam mail settings.** - If 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. + Enabling the Forward Spam setting allows you to specify `email` addresses to which spam reports will be forwarded. You can set multiple addresses by passing this endpoint a comma separated list of emails in a single string. - More Information: + ``` + { + "email": "address1@example.com, address2@exapmle.com", + "enabled": true + } + ``` - * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) - produces: - - application/json + The Forward Spam setting may also be used to receive emails sent to `abuse@` and `postmaster@` role addresses if you have authenticated your domain. + + For example, if you authenticated `example.com` as your root domain and set a custom return path of `sub` for that domain, you could turn on Forward Spam, and any emails sent to `abuse@sub.example.com` or `postmaster@sub.example.com` would be forwarded to the email address you entered in the `email` field. + + You can authenticate your domain using the #endpoint:aXpkWYramCg4ZNEGT endpoint or in the [Sender Authentication section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth). You can also configure the Forward Spam mail settings in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). parameters: - name: body in: body schema: - type: 'null' + $ref: '#/definitions/mail_settings_forward_spam' + example: + email: abuse@example.com + enabled: true + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': + '200': description: '' schema: - $ref: '#/definitions/mail_batch_id' + $ref: '#/definitions/mail_settings_forward_spam' examples: application/json: - batch_id: YOUR_BATCH_ID + email: abuse@example.com + enabled: true + '400': + $ref: '#/responses/trait:makoErrorResponse:400' '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' + '404': + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] - '/mail/batch/{batch_id}': - parameters: - - name: batch_id - in: path - required: true - type: string get: - operationId: GET_mail-batch-batch_id - summary: Validate batch ID + operationId: GET_mail_settings-forward_spam + summary: Retrieve forward spam mail settings tags: - - Cancel Scheduled Sends + - Settings - Mail description: |- - **This endpoint allows you to validate a batch ID.** - - If 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. - - More Information: + **This endpoint allows you to retrieve your current Forward Spam mail settings.** - * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) - produces: - - application/json + Enabling the Forward Spam setting allows you to specify `email` addresses to which spam reports will be forwarded. This endpoint returns any email address(es) you have set to receive forwarded spam and an `enabled` status indicating if the setting is active. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/mail_batch_id' + $ref: '#/definitions/mail_settings_forward_spam' examples: application/json: - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + email: abuse@example.com + enabled: true '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: invalid batch id + $ref: '#/responses/trait:makoErrorResponse:400' '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 + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' + '404': + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] - /user/scheduled_sends: - post: - operationId: POST_user-scheduled_sends - summary: Cancel or pause a scheduled send + /mail_settings/template: + patch: + operationId: PATCH_mail_settings-template + summary: Update template mail settings tags: - - Cancel Scheduled Sends + - Settings - Mail description: |- - **This endpoint allows you to cancel or pause an email that has been scheduled to be sent.** + **This endpoint allows you to update your current legacy email template settings.** - If the maximum number of cancellations/pauses are added, HTTP 400 will - be returned. + This setting refers to our original email templates. We currently support more fully featured [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/). - 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. - consumes: - - application/json - produces: - - application/json + The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. For instructions on using legacy templates, see how to ["Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see ["Migrating from Legacy Templates"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/). 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: + enabled: + type: boolean + description: Indicates if you want to enable the legacy email template mail setting. + html_content: 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 + description: The new HTML content for your legacy email template. example: - batch_id: YOUR_BATCH_ID - status: pause + enabled: true + html_content: <% body %> + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': - description: '' - schema: - $ref: '#/definitions/user_scheduled_send_status' - '400': - description: |- - "" : "max limit reached" - "batch_id" : "invalid batch id" - "batch_id" : "a status for this batch id exists, try PATCH to update the status" - schema: - type: object - examples: - application/json: - errors: - - field: null - message: max limit reached - - field: batch_id - message: invalid batch id - - field: batch_id - message: 'a status for this batch id exists, try PATCH to update the status' - '401': + '200': description: '' schema: type: object + properties: + enabled: + type: boolean + description: Indicates if the legacy email template mail setting is enabled. + html_content: + type: string + description: The HTML content of your legacy email template. + required: + - enabled + - html_content examples: application/json: - errors: - - field: null - message: authorization required + enabled: false + html_content: | +

<% body %>Example

+ '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' + '404': + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] get: - operationId: GET_user-scheduled_sends - summary: Retrieve all scheduled sends + operationId: GET_mail_settings-template + summary: Retrieve legacy template mail settings tags: - - Cancel Scheduled Sends + - Settings - Mail description: |- - **This endpoint allows you to retrieve all cancel/paused scheduled send information.** + **This endpoint allows you to retrieve your current legacy email template settings.** - 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. - produces: - - application/json + This setting refers to our original email templates. We currently support more fully featured [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/). + + The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. For instructions on using legacy templates, see how to ["Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see ["Migrating from Legacy Templates"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/). + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/user_scheduled_send_status' + $ref: '#/definitions/mail_settings_template' examples: application/json: - - batch_id: YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg - status: cancel - - batch_id: UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2 - status: cancel + enabled: false + html_content: | +

<% body %>Example

+ '400': + $ref: '#/responses/trait:makoErrorResponse:400' '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' + '404': + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' + security: + - Authorization: [] + /mail_settings/bounce_purge: + patch: + operationId: PATCH_mail_settings-bounce_purge + summary: Update bounce purge mail settings + tags: + - Settings - Mail + description: |- + **This endpoint allows you to update your current bounce and purge settings.** + + The Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists. The schedule is set in full days by assigning the number of days, an integer, to the `soft_bounces` and/or `hard_bounces` fields. + + A hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown. + + A soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full. + + You can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces). + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/mail_settings_bounce_purge' + example: + enabled: true + hard_bounces: 5 + soft_bounces: 5 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_bounce_purge' examples: application/json: - errors: - - field: null - message: authorization required + enabled: false + hard_bounces: 5 + soft_bounces: 5 + '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' + '404': + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] - '/user/scheduled_sends/{batch_id}': - parameters: - - name: batch_id - in: path - required: true - type: string get: - operationId: GET_user-scheduled_sends-batch_id - summary: Retrieve scheduled send + operationId: GET_mail_settings-bounce_purge + summary: Retrieve bounce purge mail settings tags: - - Cancel Scheduled Sends + - Settings - Mail description: |- - **This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.** + **This endpoint allows you to retrieve your current bounce and purge settings.** - 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. - produces: - - application/json + The Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists. + + A hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown. + + A soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full. + + You can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces). + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - title: Retrieve scheduled send response - items: - $ref: '#/definitions/user_scheduled_send_status' + $ref: '#/definitions/mail_settings_bounce_purge' examples: application/json: - - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi - status: cancel - - batch_id: IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg - status: pause + enabled: false + soft_bounces: 5 + hard_bounces: 5 + '400': + $ref: '#/responses/trait:makoErrorResponse:400' '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' + '404': + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] + /mail_settings/forward_bounce: patch: - operationId: PATCH_user-scheduled_sends-batch_id - summary: Update user scheduled send information + operationId: PATCH_mail_settings-forward_bounce + summary: Update forward bounce mail settings tags: - - Cancel Scheduled Sends + - Settings - Mail description: |- - **This endpoint allows you to update the status of a scheduled send for the given `batch_id`.** + **This endpoint allows you to update your current bounce forwarding mail settings.** - 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. - consumes: - - application/json - produces: - - application/json + Enabling the Forward Bounce setting allows you to specify an `email` address to which bounce reports will be forwarded. + + You can also configure the Forward Spam mail settings in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). 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 + $ref: '#/definitions/mail_settings_forward_bounce' example: - status: pause + enabled: true + email: bounces@example.com + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': - description: '' - schema: - type: 'null' - '400': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_forward_bounce' examples: application/json: - errors: - - field: status - message: status must be either cancel or pause + email: bounces@example.com + enabled: true + '400': + $ref: '#/responses/trait:makoErrorResponse:400' '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' + '404': + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' + security: + - Authorization: [] + get: + operationId: GET_mail_settings-forward_bounce + summary: Retrieve forward bounce mail settings + tags: + - Settings - Mail + description: |- + **This endpoint allows you to retrieve your current bounce forwarding mail settings.** + + Enabling the Forward Bounce setting allows you to specify `email` addresses to which bounce reports will be forwarded. This endpoint returns the email address you have set to receive forwarded bounces and an `enabled` status indicating if the setting is active. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_forward_bounce' examples: application/json: - errors: - - field: null - message: authorization required + enabled: true + email: bounces@example.com + '400': + $ref: '#/responses/trait:makoErrorResponse:400' + '401': + $ref: '#/responses/trait:makoErrorResponse:401' + '403': + $ref: '#/responses/trait:makoErrorResponse:403' '404': - description: '"" : "batch id not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: batch id not found + $ref: '#/responses/trait:makoErrorResponse:404' + '500': + $ref: '#/responses/trait:makoErrorResponse:500' security: - Authorization: [] - delete: - operationId: DELETE_user-scheduled_sends-batch_id - summary: Delete a cancellation or pause of a scheduled send + /partner_settings/new_relic: + patch: + operationId: PATCH_partner_settings-new_relic + summary: Updates New Relic partner settings. tags: - - Cancel Scheduled Sends + - Settings - Partner description: |- - **This endpoint allows you to delete the cancellation/pause of a scheduled send.** + **This endpoint allows you to update or change your New Relic partner settings.** - 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. - produces: - - application/json + 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 [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/). + + 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 [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/). parameters: - name: body in: body schema: - type: 'null' + type: object + properties: + license_key: + type: string + description: The license key for your New Relic account. + enabled: + type: boolean + description: Indicates if this partner setting is enabled. + enable_subuser_statistics: + type: boolean + description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. + example: + license_key: '' + enabled: true + enable_subuser_statistics: true + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': - description: '' - schema: - type: 'null' - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/partner_settings_new_relic' examples: application/json: - errors: - - field: null - message: batch id not found + enable_subuser_statistics: true + enabled: true + license_key: '' security: - Authorization: [] - /categories: get: - operationId: GET_categories - summary: Retrieve all categories + operationId: GET_partner_settings-new_relic + summary: Returns all New Relic partner settings. tags: - - Categories + - Settings - Partner description: |- - **This endpoint allows you to retrieve a list of all of your categories.** + **This endpoint allows you to retrieve your current New Relic partner settings.** - Categories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - produces: - - application/json + 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 [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/). + + 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 [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/). parameters: - - name: limit - in: query - description: The number of categories to display per page. - type: integer - default: 50 - - name: category + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/partner_settings_new_relic' + examples: + application/json: + enable_subuser_statistics: false + enabled: true + license_key: '' + security: + - Authorization: [] + /partner_settings: + get: + operationId: GET_partner_settings + summary: Returns a list of all partner settings. + tags: + - Settings - Partner + 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 [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/). + parameters: + - name: limit in: query - description: Allows you to perform a prefix search on this particular category. - type: string + description: The number of settings to return per page. + type: integer - name: offset in: query - description: The point in the list that you would like to begin displaying results. + description: The paging offset. type: integer - default: 0 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - type: object - properties: - category: + 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. + security: + - Authorization: [] + /teammates: + post: + operationId: POST_v3-teammates + summary: Invite teammate + tags: + - Teammates + description: |- + **This endpoint allows you to invite a Teammate to your account via email.** + + You can set a Teammate's initial permissions using the `scopes` array in the request body. Teammate's will receive a minimum set of scopes from Twilio SendGrid that are necessary for the Teammate to function. + + **Note:** A teammate invite will expire after 7 days, but you may resend the invitation at any time to reset the expiration date. + parameters: + - name: body + in: body + schema: + type: object + properties: + email: + type: string + description: New teammate's email + minLength: 5 + maxLength: 255 + pattern: ^.*@.*\..* + scopes: + type: array + description: Set to specify list of scopes that teammate should have. Should be empty if teammate is an admin. + items: type: string - description: A category used to group emails by broad topic. - required: - - category + is_admin: + type: boolean + default: false + description: Set to true if teammate should be an admin user + required: + - email + - scopes + - is_admin + example: + email: teammate1@example.com + scopes: + - user.profile.read + - user.profile.update + is_admin: false + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': + description: '' + schema: + type: object + properties: + token: + type: string + description: Token to identify invite + email: + type: string + description: Teammate's email address + scopes: + type: array + description: Initial set of permissions to give to teammate if they accept the invite + items: {} + is_admin: + type: boolean + description: Set to true if teammate should have admin privileges examples: application/json: - - category: category 1 - - category: category 2 + email: teammate1@example.com + scopes: + - user.profile.read + - user.profile.update + is_admin: false '400': description: '' schema: @@ -2948,1009 +2774,968 @@ paths: properties: errors: type: array - description: The error returned. items: type: object properties: - field: - type: string message: type: string - description: A message explaining why your categories could not be retrieved. - required: - - field - - message - examples: - application/json: - errors: - - field: sort_by - message: invalid sort value + field: + type: string security: - Authorization: [] - /categories/stats/sums: get: - operationId: GET_categories-stats-sums - summary: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' + operationId: GET_v3-teammates + summary: Retrieve all teammates tags: - - Categories + - Teammates description: |- - **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.** - - If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. + **This endpoint allows you to retrieve a list of all current Teammates.** - Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - produces: - - application/json + You can limit the number of results returned using the `limit` query paramater. To return results from a specific Teammate, use the `offset` paramter. The Response Headers will include pagination info. parameters: - - name: sort_by_metric - in: query - description: The metric that you want to sort by. Must be a single metric. - required: false - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - type: string - - name: end_date - in: query - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. - required: false - type: string - name: limit in: query - description: Limits the number of results returned. - required: false + description: Number of items to return type: integer - default: 5 + default: 500 + minimum: 0 + maximum: 500 - name: offset in: query - description: The point in the list to begin retrieving results. - required: false + description: Paging offset type: integer default: 0 - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month + minimum: 0 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $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 + type: object + properties: + result: + type: array + items: + type: object + properties: + username: + type: string + description: Teammate's username + email: + type: string + description: Teammate's email + first_name: + type: string + description: Teammate's first name + last_name: + type: string + description: Teammate's last name + user_type: + type: string + description: 'Indicate the type of user: owner user, teammate admin user, or normal teammate' + enum: + - admin + - owner + - teammate + is_admin: + type: boolean + description: Set to true if teammate has admin privileges + phone: + type: string + description: (optional) Teammate's phone number + website: + type: string + description: (optional) Teammate's website + address: + type: string + description: (optional) Teammate's address + address2: + type: string + description: (optional) Teammate's address + city: + type: string + description: (optional) Teammate's city + state: + type: string + description: (optional) Teammate's state + zip: + type: string + description: (optional) Teammate's zip + country: + type: string + description: (optional) Teammate's country + examples: + application/json: + results: + - username: teammate1 + email: teammate1@example.com + first_name: Jane + last_name: Doe + user_type: owner + is_admin: true + phone: 123-345-3453 + website: www.example.com + company: ACME Inc. + address: 123 Acme St + address2: '' + city: City + state: CA + country: USA + zip: '12345' + - username: teammate2 + email: teammate2@example.com + first_name: John + last_name: Doe + user_type: teammate + is_admin: false + phone: 123-345-3453 + website: www.example.com + company: ACME Inc. + address: 123 Acme St + address2: '' + city: City + state: CA + country: USA + zip: '12345' + - username: teammate3 + email: teammate3@example.com + first_name: Steve + last_name: Doe + user_type: admin + is_admin: true + phone: 123-345-3453 + website: www.example.com + company: ACME Inc. + address: 123 Acme St + address2: '' + city: City + state: CA + country: USA + zip: '12345' security: - Authorization: [] - /categories/stats: - get: - operationId: GET_categories-stats - summary: Retrieve Email Statistics for Categories + '/teammates/pending/{token}/resend': + parameters: + - name: token + in: path + description: The token for the invite that you want to resend. + required: true + type: string + post: + operationId: POST_v3-teammates-pending-token-resend + summary: Resend teammate invite tags: - - Categories + - Teammates description: |- - **This endpoint allows you to retrieve all of your email statistics for each of your categories.** + **This endpoint allows you to resend a Teammate invitation.** - If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. + Teammate invitations will expire after 7 days. Resending an invitation will reset the expiration date. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + token: + type: string + description: ID to identify invite + email: + type: string + description: Teammate's email address + scopes: + type: array + description: Initial set of permissions to give to teammate if they accept the invite + items: + type: string + is_admin: + type: boolean + description: Set to true if teammate should have admin privileges + examples: + application/json: + pending_id: abc123abc + email: teammate1@example.com + scopes: + - user.profile.read + - user.profile.update + is_admin: false + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: invalid pending key + field: pending_key + security: + - Authorization: [] + /scopes/requests: + get: + operationId: GET_v3-scopes-requests + summary: Retrieve access requests + tags: + - Teammates + description: |- + **This endpoint allows you to retrieve a list of all recent access requests.** - Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - produces: - - application/json + The Response Header's `link` parameter will include pagination info. 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 + description: Optional field to limit the number of results returned. type: integer - default: 500 - maximum: 500 + default: 50 - name: offset in: query - description: The number of results to skip. - required: false + description: Optional beginning point in the list to retrieve from. 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 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + default: 0 responses: '200': description: '' schema: type: array items: - $ref: '#/definitions/category_stats' + type: object + properties: + id: + type: integer + description: Request ID + scope_group_name: + type: string + description: Name of group of scopes associated to page teammate is requesting access to + username: + type: string + description: Teammate's username + email: + type: string + description: Teammate's email + first_name: + type: string + description: Teammate's first name + last_name: + type: string + description: Teammate's last name examples: application/json: - - date: '2015-10-01' - stats: - - type: category - name: docs - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - type: category - name: mattscategory - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - date: '2015-11-01' - stats: - - type: category - name: docs - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - - type: category - name: mattscategory - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - security: - - Authorization: [] - /contactdb/custom_fields: - post: - operationId: POST_contactdb-custom_fields - summary: Create a Custom Field - tags: - - Contacts API - Custom Fields - description: |- - **This endpoint allows you to 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - type: - type: string - example: - name: pet - type: text - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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" - "type" : "Returned if custom field type is invalid or not provided" - "name" : "Returned if custom field name is not provided" - schema: - $ref: '#/definitions/errors' - 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 + - id: 1 + scope_group_name: Mail Settings + username: teammate1 + email: teammate1@example.com + first_name: Teammate + last_name: One + - id: 2 + scope_group_name: Stats + username: teammate2 + email: teammate2@example.com + first_name: Teammate + last_name: Two security: - Authorization: [] + /teammates/pending: get: - operationId: GET_contactdb-custom_fields - summary: Retrieve all custom fields + operationId: GET_v3-teammates-pending + summary: Retrieve all pending teammates tags: - - Contacts API - Custom Fields + - Teammates description: |- - **This endpoint allows you to retrieve all custom fields.** + **This endpoint allows you to retrieve a list of all pending Teammate invitations.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - produces: - - application/json + Each teammate invitation is valid for 7 days. Users may resend the invitation to refresh the expiration date. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - title: List All Custom Fields response type: object properties: - custom_fields: + result: type: array items: - $ref: '#/definitions/contactdb_custom_field_with_id' - required: - - custom_fields - examples: - application/json: - custom_fields: - - id: 6234 - name: age - type: number - - id: 6233 - name: country - type: text - - id: 6235 - name: favorite_color - type: text - - id: 6239 - name: fname - type: text - - id: 6240 - name: lname - type: text - - id: 49439 - name: pet - type: text - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + email: + type: string + description: Email address teammate invite will be sent to + scopes: + type: array + description: List of permissions to give teammate if they accept + items: + type: string + is_admin: + type: boolean + description: Set to true to indicate teammate should have the same set of permissions as parent user + token: + type: string + description: Invitation token used to identify user + expiration_date: + type: integer + description: timestamp indicates when invite will expire. Expiration is 7 days after invite creation examples: application/json: - errors: - - field: null - message: authorization required + result: + - email: user1@example.com + scopes: + - user.profile.read + - user.profile.edit + is_admin: false + pending_id: abcd123abc + expiration_date: 1456424263 + - email: user2@example.com + scopes: [] + is_admin: true + pending_id: bcde234bcd + expiration_date: 1456424263 security: - Authorization: [] - '/contactdb/custom_fields/{custom_field_id}': + '/teammates/{username}': parameters: - - name: custom_field_id + - name: username in: path - description: The ID of the custom field that you want to retrieve. + description: The username of the teammate that you want to retrieve. required: true - type: integer + type: string get: - operationId: GET_contactdb-custom_fields-custom_field_id - summary: Retrieve a Custom Field + operationId: GET_v3-teammates-username + summary: Retrieve specific teammate tags: - - Contacts API - Custom Fields + - Teammates description: |- - **This endpoint allows you to retrieve a custom field by ID.** + **This endpoint allows you to retrieve a specific Teammate by username.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - produces: - - application/json + You can retrieve the username's for each of your Teammates using the #endpoint:DiW4xbhq35GgRP6Mp endpoint. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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' + type: object + properties: + username: + type: string + description: Teammate's username + first_name: + type: string + description: Teammate's first name + last_name: + type: string + description: Teammate's last name + email: + type: string + description: Teammate's email + scopes: + type: array + description: Scopes associated to teammate + items: {} + user_type: + type: string + description: 'Indicate the type of user: account owner, teammate admin user, or normal teammate' + enum: + - admin + - owner + - teammate + is_admin: + type: boolean + description: Set to true if teammate has admin privileges + phone: + type: string + description: (optional) Teammate's phone number + website: + type: string + description: (optional) Teammate's website + address: + type: string + description: (optional) Teammate's address + address2: + type: string + description: (optional) Teammate's address + city: + type: string + description: (optional) Teammate's city + state: + type: string + description: (optional) Teammate's state + zip: + type: string + description: (optional) Teammate's zip + country: + type: string + description: (optional) Teammate's country examples: application/json: - errors: - - message: Custom field ID does not exist + username: teammate1 + first_name: Jane + last_name: Doe + email: teammate1@example.com + scopes: + - user.profile.read + - user.profile.update + - ... + user_type: admin + is_admin: true + phone: 123-345-3453 + website: www.example.com + company: ACME Inc. + address: 123 Acme St + address2: '' + city: City + state: CA + country: USA + zip: '12345' security: - Authorization: [] - delete: - operationId: DELETE_contactdb-custom_fields-custom_field_id - summary: Delete a Custom Field + patch: + operationId: PATCH_v3-teammates-username + summary: Update teammate's permissions tags: - - Contacts API - Custom Fields + - Teammates description: |- - **This endpoint allows you to delete a custom field by ID.** + **This endpoint allows you to update a teammate’s permissions.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - produces: - - application/json + To turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have. + + **Only the parent user or other admin teammates can update another teammate’s permissions.** + + **Admin users can only update permissions.** parameters: - name: body in: body schema: - type: 'null' + type: object + properties: + scopes: + type: array + description: 'Provide list of scopes that should be given to teammate. If specifying list of scopes, is_admin should be set to False.' + items: + type: string + is_admin: + type: boolean + description: 'Set to True if this teammate should be promoted to an admin user. If True, scopes should be an empty array.' + required: + - scopes + - is_admin + example: + scopes: + - user.profile.read + - user.profile.edit + is_admin: false - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '202': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + username: + type: string + description: Teammate's username + first_name: + type: string + description: Teammate's first name + last_name: + type: string + description: Teammate's last name + email: + type: string + description: Teammate's email address + scopes: + type: array + description: Scopes given to teammate + items: + type: string + user_type: + type: string + description: 'Indicate the type of user: owner user, teammate admin user, or normal teammate' + enum: + - admin + - owner + - teammate + is_admin: + type: boolean + description: Set to true if teammate has admin priveleges + phone: + type: string + description: (optional) Teammate's phone number + website: + type: string + description: (optional) Teammate's website + address: + type: string + description: (optional) Teammate's address + address2: + type: string + description: (optional) Teammate's address + city: + type: string + description: (optional) Teammate's city + state: + type: string + description: (optional) Teammate's state + zip: + type: string + description: (optional) Teammate's zip + country: + type: string + description: (optional) Teammate's country examples: application/json: - message: Custom Field delete is processing. + username: teammate1 + first_name: Jane + last_name: Doe + email: teammate1@example.com + scopes: + - user.profile.read + - user.profile.edit + user_type: teammate + is_admin: false + phone: 123-345-3453 + website: www.example.com + company: ACME Inc. + address: 123 Acme St + address2: '' + city: City + state: CA + country: USA + zip: '12345' '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' + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string examples: application/json: errors: - - field: null - message: authorization required + - message: one or more of given scopes are invalid + field: scopes '404': - description: '"custom_field_id" : "Returned if custom_field_id does not exist"' + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string examples: application/json: errors: - - message: Custom field ID does not exist + - message: username not found + field: username security: - Authorization: [] - /contactdb/reserved_fields: - get: - operationId: GET_contactdb-reserved_fields - summary: Retrieve reserved fields + delete: + operationId: DELETE_v3-teammates-username + summary: Delete teammate tags: - - Contacts API - Custom Fields + - Teammates description: |- - **This endpoint allows you to list all fields that are reserved and can't be used for custom field names.** + **This endpoint allows you to delete a teammate.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - produces: - - application/json + **Only the parent user or an admin teammate can delete another teammate.** parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' schema: - title: List fields that are reserved and can't be used for custom field names. response type: object properties: - reserved_fields: + errors: 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': + type: object + properties: + message: + type: string + field: + type: string + '404': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string examples: application/json: errors: - - field: null - message: authorization required + - message: username not found + field: username security: - Authorization: [] - /contactdb/lists: - post: - operationId: POST_contactdb-lists - summary: Create a List + '/scopes/requests/{request_id}/approve': + parameters: + - name: request_id + in: path + description: The ID of the request that you want to approve. + required: true + type: string + patch: + operationId: PATCH_v3-scopes-requests-approve-id + summary: Approve access request tags: - - Contacts API - Lists + - Teammates description: |- - **This endpoint allows you to create a list for your recipients.** + **This endpoint allows you to approve an access attempt.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body + **Note:** Only teammate admins may approve another teammate’s access request. + responses: + '200': + description: '' schema: - title: Create a List request type: object properties: - name: + scope_group_name: type: string - required: - - name - example: - name: your list name - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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' + description: name of feature teammate will be given access to 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 + scope_group_name: Stats '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - get: - operationId: GET_contactdb-lists - summary: Retrieve all lists - tags: - - Contacts API - Lists - description: |- - **This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': + type: object + '404': description: '' schema: - title: List All Lists response type: object properties: - lists: + errors: type: array items: - $ref: '#/definitions/contactdb_list' - required: - - lists - examples: - application/json: - lists: - - id: 1 - name: the jones - recipient_count: 1 + type: object + properties: + message: + type: string + field: + type: string security: - Authorization: [] + '/scopes/requests/{request_id}': + parameters: + - name: request_id + in: path + description: The ID of the request that you want to deny. + required: true + type: string delete: - operationId: DELETE_contactdb-lists - summary: Delete Multiple lists + operationId: DELETE_v3-scopes-requests-request_id + summary: Deny access request tags: - - Contacts API - Lists + - Teammates description: |- - **This endpoint allows you to delete multiple recipient lists.** + **This endpoint allows you to deny an attempt to access your account.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: array - items: - type: integer - example: - - 1 - - 2 - - 3 - - 4 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + **Note:** Only teammate admins may delete a teammate's access request. 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: '' + '404': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string examples: application/json: errors: - - field: null - message: authorization required + - message: Cannot find request + field: request_id security: - Authorization: [] - '/contactdb/lists/{list_id}': + '/teammates/pending/{token}': parameters: - - name: list_id + - name: token in: path + description: The token for the invite you want to delete. required: true type: string - get: - operationId: GET_contactdb-lists-list_id - summary: Retrieve a single list + delete: + operationId: DELETE_v3-teammates-pending-token + summary: Delete pending teammate tags: - - Contacts API - Lists - description: |- - This endpoint allows you to retrieve a single recipient list. - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + - Teammates + description: '**This endpoint allows you to delete a pending teammate invite.**' parameters: - - name: list_id - in: query - description: The ID of the list to retrieve. - type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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': + '204': description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required '404': - description: '"list_id" : "Returned if list_id does not exist"' + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: + type: object + properties: errors: - - field: null - message: List ID does not exist + type: array + items: + type: object + properties: + message: + type: string + field: + type: string security: - Authorization: [] - patch: - operationId: PATCH_contactdb-lists-list_id - summary: Update a List + /alerts: + post: + operationId: POST_alerts + summary: Create a new Alert tags: - - Contacts API - Lists + - Alerts description: |- - **This endpoint allows you to update the name of one of your recipient lists.** + **This endpoint allows you to create a new alert.** + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint: - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - consumes: - - application/json - produces: - - application/json - parameters: - - name: list_id - in: query - description: The ID of the list you are updating. - required: true - type: integer + * `usage_limit` allows you to set the threshold at which an alert will be sent. + * `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + For more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/). + parameters: - name: body in: body schema: - title: Update a List request type: object properties: - name: + type: type: string - description: 'The new name for your list. ' + description: |- + The type of alert you want to create. Can be either usage_limit or stats_notification. + Example: usage_limit + enum: + - stats_notification + - usage_limit + email_to: + type: string + description: |- + The email address the alert will be sent to. + Example: test@example.com + format: email + nullable: true + frequency: + type: string + description: |- + Required for stats_notification. How frequently the alert will be sent. + Example: daily + percentage: + type: integer + description: |- + Required for usage_alert. When this usage threshold is reached, the alert will be sent. + Example: 90 required: - - name + - type + - email_to example: - name: newlistname - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + type: stats_notification + email_to: example@example.com + frequency: daily + - name: Authorization + in: header + type: string + - name: on-behalf-of + in: header + type: string responses: - '200': + '201': description: '' schema: type: object properties: + created_at: + type: integer + description: A Unix timestamp indicating when the alert was created. + email_to: + type: string + description: The email address that the alert will be sent to. + format: email + frequency: + type: string + description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly".' id: type: integer - description: The ID of the list - name: + description: The ID of the alert. + type: type: string - description: The new name for the list - recipient_count: + description: The type of alert. + updated_at: type: integer - description: The number of recipients on the list + description: A Unix timestamp indicating when the alert was last modified. + percentage: + type: integer + description: '"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' + required: + - created_at + - email_to + - id + - type + - updated_at examples: application/json: - id: 1234 - name: 2016 iPhone Users - recipient_count: 0 + created_at: 1451520930 + email_to: test@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451520930 '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"' + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: List ID does not exist + type: object + properties: + field: + type: string + message: + type: string security: - Authorization: [] - delete: - operationId: DELETE_contactdb-lists-list_id - summary: Delete a List + get: + operationId: GET_alerts + summary: Retrieve all alerts tags: - - Contacts API - Lists + - Alerts description: |- - **This endpoint allows you to delete a specific recipient list with the given ID.** + **This endpoint allows you to retrieve all of your alerts.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + For more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/). 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 - - name: body - in: body - schema: - type: 'null' + - name: Authorization + in: header + type: string - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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: array + description: The list of alerts. + items: + type: object + properties: + created_at: + type: integer + description: A Unix timestamp indicating when the alert was created. + email_to: + type: string + description: The email address that the alert will be sent to. + id: + type: integer + description: The ID of the alert. + percentage: + type: integer + description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' + type: + type: string + description: The type of alert. + enum: + - usage_limit + - stats_notification + updated_at: + type: integer + description: A Unix timestamp indicating when the alert was last modified. + frequency: + type: string + description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, "daily", "weekly", or "monthly".' + required: + - created_at + - email_to + - id + - type examples: application/json: - errors: - - message: 'List not found: 5' + - created_at: 1451498784 + email_to: example1@example.com + id: 46 + percentage: 90 + type: usage_limit + updated_at: 1451498784 + - created_at: 1451498812 + email_to: example2@example.com + frequency: monthly + id: 47 + type: stats_notification + updated_at: 1451498812 + - created_at: 1451520930 + email_to: example3@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451520930 security: - Authorization: [] - '/contactdb/lists/{list_id}/recipients': + '/alerts/{alert_id}': parameters: - - name: list_id + - name: alert_id in: path - description: The id of the list of recipients you want to retrieve. + description: The ID of the alert you would like to retrieve. required: true type: integer get: - operationId: GET_contactdb-lists-list_id-recipients - summary: Retrieve all recipients on a List + operationId: GET_alerts-alert_id + summary: Retrieve a specific alert tags: - - Contacts API - Lists + - Alerts description: |- - **This endpoint allows you to retrieve all recipients on the list with the given ID.** + **This endpoint allows you to retrieve a specific alert.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + For more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/). parameters: - - name: page - in: query - description: Page index of first recipient to return (must be a positive integer) - required: false - type: integer - - name: page_size - in: query - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - required: false - type: integer - - name: list_id - in: query - description: The ID of the list whose recipients you are requesting. - required: true - type: integer + - name: Authorization + in: header + type: string - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': @@ -3958,300 +3743,319 @@ paths: 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" - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: 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 + created_at: + type: integer + description: A Unix timestamp indicating when the alert was created. + email_to: + type: string + description: The email address that the alert will be sent to. + frequency: + type: string + description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly".' + id: + type: integer + description: The ID of the alert. + type: + type: string + description: The type of alert. + enum: + - usage_alert + - stats_notification + updated_at: + type: integer + description: A Unix timestamp indicating when the alert was last modified. + percentage: + type: integer + description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' + required: + - created_at + - email_to + - id + - type + - updated_at examples: application/json: - errors: - - field: list_id - message: Returned if list_id is invalid + created_at: 1451520930 + email_to: example@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451520930 security: - Authorization: [] - post: - operationId: POST_contactdb-lists-list_id-recipients - summary: Add Multiple Recipients to a List + delete: + operationId: DELETE_alerts-alert_id + summary: Delete an alert tags: - - Contacts API - Lists + - Alerts description: |- - **This endpoint allows you to add multiple recipients to a list.** + **This endpoint allows you to delete an alert.** - 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. + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - consumes: - - application/json - produces: - - application/json + For more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/). parameters: - - name: body - in: body - schema: - type: array - items: - type: string - example: - - recipient_id1 - - recipient_id2 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': - description: '' - schema: - type: 'null' - '400': - description: |- - "list_id" : "Returned if list_id is not a valid integer" - "" : "Returned if no valid recipient ids were passed" - "" : "Returned if no recipients were added" - "" : "Returned if request body is invalid JSON" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: list_id - message: list_id is invalid - - field: recipient_id - message: no valid recipients were provided - - field: null - message: no recipients were added - - field: null - message: request body is invalid JSON - '401': + '204': 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 + type: object + properties: {} security: - Authorization: [] - '/contactdb/lists/{list_id}/recipients/{recipient_id}': - parameters: - - name: list_id - in: path - description: The ID of the list that you want to add the recipient to. - required: true - type: integer - - name: recipient_id - in: path - description: The ID of the recipient you are adding to the list. - required: true - type: string - post: - operationId: POST_contactdb-lists-list_id-recipients-recipient_id - summary: Add a Single Recipient to a List + patch: + operationId: PATCH_alerts-alert_id + summary: Update an alert tags: - - Contacts API - Lists + - Alerts description: |- - **This endpoint allows you to add a single recipient to a list.** + **This endpoint allows you to update an alert.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + * Usage alerts allow you to set the threshold at which an alert will be sent. + * Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + + For more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/). parameters: - name: body in: body schema: - type: 'null' + type: object + properties: + email_to: + type: string + description: |- + The new email address you want your alert to be sent to. + Example: test@example.com + frequency: + type: string + description: |- + The new frequency at which to send the stats_notification alert. + Example: monthly + percentage: + type: integer + description: |- + The new percentage threshold at which the usage_limit alert will be sent. + Example: 90 + example: + email_to: example@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': + '200': 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' + type: object + properties: + created_at: + type: integer + description: A Unix timestamp indicating when the alert was created. + email_to: + type: string + description: The email address that the alert will be sent to. + frequency: + type: string + description: 'If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: "daily", "weekly", or "monthly".' + id: + type: integer + description: The ID of the alert. + type: + type: string + description: The type of alert. + enum: + - usage_alert + - stats_notification + updated_at: + type: integer + description: A Unix timestamp indicating when the alert was last modified. + percentage: + type: integer + description: 'If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent.' + required: + - created_at + - email_to + - id + - type + - updated_at examples: application/json: - errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: Returned if recipient_id is invalid - '401': + created_at: 1451520930 + email_to: example@example.com + frequency: daily + id: 48 + type: stats_notification + updated_at: 1451522691 + security: + - Authorization: [] + /user/profile: + get: + operationId: GET_user-profile + summary: Get a user's profile + tags: + - Users API + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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' + 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: - errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist + address: 814 West Chapman Avenue + address2: '' + city: Orange + company: SendGrid + country: US + first_name: Test + last_name: User + phone: 555-555-5555 + state: CA + website: 'http://www.sendgrid.com' + zip: '92868' security: - Authorization: [] - delete: - operationId: DELETE_contactdb-lists-list_id-recipients-recipient_id - summary: Delete a Single Recipient from a Single List + patch: + operationId: PATCH_user-profile + summary: Update a user's profile tags: - - Contacts API - Lists + - Users API description: |- - **This endpoint allows you to delete a single recipient from a list.** + **This endpoint allows you to update your current profile details.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + Any one or more of the parameters can be updated via the PATCH `/user/profile` endpoint. You must include at least one when you PATCH. parameters: - - name: list_id - in: query - description: The ID of the list you are taking this recipient away from. - required: true - type: integer - - name: recipient_id - in: query - description: The ID of the recipient to take off the list. - required: true - type: integer - name: body in: body schema: - type: 'null' + $ref: '#/definitions/user_profile' + example: + first_name: Example + last_name: User + city: Orange - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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/user_profile' examples: application/json: - errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: no valid recipients were provided + 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' + $ref: '#/definitions/global_error_response_schema' 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" + security: + - Authorization: [] + /user/account: + get: + operationId: GET_user-account + summary: Get a user's account information. + tags: + - Users API + description: |- + **This endpoint allows you to retrieve your user account details.** + + Your user's account information includes the user's account type and reputation. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + title: GET User Account response + type: object + properties: + type: + type: string + description: The type of account for this user. + enum: + - free + - paid + reputation: + type: number + description: The sender reputation for this user. + required: + - type + - reputation examples: application/json: - errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist + reputation: 100 + type: paid security: - Authorization: [] - /contactdb/status: + /user/email: get: - operationId: GET_contactdb-status - summary: Get Contact Upload Status + operationId: GET_user-email + summary: Retrieve your account email address tags: - - Contacts API - Recipients - consumes: - - application/json - produces: - - application/json + - Users API + description: '**This endpoint allows you to retrieve the email address currently on file for your account.**' parameters: - - $ref: '#/parameters/trait:authorizationHeader:Authorization' - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': @@ -4259,474 +4063,425 @@ paths: schema: type: object properties: - status: - type: array - items: - type: object - properties: - id: - type: string - value: - type: string + email: + type: string + description: The email address currently on file for your account. + format: email + required: + - email examples: application/json: - status: - - id: worker_delay - value: delayed - - id: worker_delay_seconds - value: '75.0' - /contactdb/recipients: - post: - operationId: POST_contactdb-recipients - summary: Add recipients + email: test@example.com + security: + - Authorization: [] + put: + operationId: PUT_user-email + summary: Update your account email address tags: - - Contacts API - Recipients - description: |- - **This endpoint allows you to add a Marketing Campaigns recipient.** - - 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 Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - consumes: - - application/json - produces: - - application/json + - Users API + description: '**This endpoint allows you to update the email address currently on file for your account.**' parameters: - name: body in: body schema: - type: array - items: - type: object - properties: - email: - type: string - description: The email address of the recipient. - format: email - first_name: - type: string - description: The first name of the recipient. - last_name: - type: string - description: The last name of the recipient. - age: - type: integer - required: - - email + type: object + properties: + email: + type: string + description: The new email address that you would like to use for your account. example: - - email: example@example.com - first_name: '' - last_name: User - age: 25 - - email: example2@example.com - first_name: Example - last_name: User - age: 25 + email: example@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': - description: '' - schema: - $ref: '#/definitions/contactdb_recipient_response' - examples: - application/json: - error_count: 1 - error_indices: - - 2 - new_count: 2 - persisted_recipients: - - YUBh - - bWlsbGVyQG1pbGxlci50ZXN0 - updated_count: 0 - errors: - - message: Invalid email. - error_indices: - - 2 - '400': - description: '"" : "Returned if request body is not valid json"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: Request body is not valid json - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + email: + type: string + description: The current email address on file for your account. + format: email + required: + - email examples: application/json: - errors: - - field: null - message: authorization required + email: example@example.com security: - Authorization: [] - patch: - operationId: PATCH_contactdb-recipients - summary: Update Recipient + /user/username: + get: + operationId: GET_user-username + summary: Retrieve your username tags: - - Contacts API - Recipients - description: |- - **This endpoint allows you to update one or more recipients.** - - The body of an API call to this endpoint must include an array of one or more recipient objects. - - 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). - consumes: - - application/json - produces: - - application/json + - Users API + description: '**This endpoint allows you to retrieve your current account username.**' parameters: - - name: body - in: body - 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. - required: - - email - example: - - email: jones@example.com - last_name: Jones - first_name: Guy - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + username: + type: string + description: Your account username. + user_id: + type: integer + description: The user ID for your account. + required: + - username + - user_id examples: application/json: - errors: - - field: null - message: authorization required + username: test_username + user_id: 1 security: - Authorization: [] - delete: - operationId: DELETE_contactdb-recipients - summary: Delete Recipient + put: + operationId: PUT_user-username + summary: Update your username tags: - - Contacts API - Recipients - description: |- - **This endpoint allows you to deletes one or more recipients.** - - The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. - - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - consumes: - - application/json - produces: - - application/json + - Users API + description: '**This endpoint allows you to update the username for your account.**' parameters: - name: body in: body schema: - type: array - items: - type: string + type: object + properties: + username: + type: string + description: The new username you would like to use for your account. example: - - recipient_id1 - - recipient_id2 + username: test_username - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: type: object - '400': - description: |- - "" : "Returned if no recipients are deleted" - "" : "Returned if all of the provided recipient ids are invalid" - "" : "Returned if request body is not valid json" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: No recipient ids provided - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + properties: + username: + type: string + description: The current username on file for your account. + required: + - username examples: application/json: - errors: - - field: null - message: authorization required + username: test_username security: - Authorization: [] + /user/credits: get: - operationId: GET_contactdb-recipients - summary: Retrieve recipients + operationId: GET_user-credits + summary: Retrieve your credit balance tags: - - Contacts API - Recipients + - Users API description: |- - **This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** - - Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of - the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. + **This endpoint allows you to retrieve the current credit balance for your account.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + Each account has a credit balance, which is a base number of emails it can send before receiving per-email charges. For more information about credits and billing, see [Billing and Plan details information](https://sendgrid.com/docs/ui/account-and-settings/billing/). 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 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - title: List Recipients response type: object properties: - recipients: - type: array - items: - type: object + remain: + type: integer + description: The remaining number of credits available on your account. + total: + type: integer + description: The total number of credits assigned to your account. + overage: + type: integer + description: The number of overdrawn credits for your account. + used: + type: integer + description: The number of credits that you have used. + last_reset: + type: string + description: The date that your credit balance was last reset. + next_reset: + type: string + description: The next date that your credit balance will be reset. + reset_frequency: + type: string + description: The frequency at which your credit balance will be reset. required: - - recipients - '400': - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" - schema: - type: object - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + - remain + - total + - overage + - used + - last_reset + - next_reset + - reset_frequency examples: application/json: - errors: - - field: null - message: authorization required + remain: 200 + total: 200 + overage: 0 + used: 0 + last_reset: '2013-01-01' + next_reset: '2013-02-01' + reset_frequency: monthly security: - Authorization: [] - '/contactdb/recipients/{recipient_id}': - parameters: - - name: recipient_id - in: path - description: The ID of the recipient that you want to retrieve. - required: true - type: string + /user/password: + put: + operationId: PUT_user-password + summary: Update your password + tags: + - Users API + description: '**This endpoint allows you to update your password.**' + parameters: + - name: body + in: body + schema: + type: object + properties: + new_password: + type: string + description: The new password you would like to use for your account. + old_password: + type: string + description: The old password for your account. + required: + - new_password + - old_password + example: + new_password: new_password + old_password: old_password + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: {} + security: + - Authorization: [] + /subusers: get: - operationId: GET_contactdb-recipients-recipient_id - summary: Retrieve a single recipient + operationId: GET_subusers + summary: List all Subusers tags: - - Contacts API - Recipients + - Subusers API description: |- - **This endpoint allows you to retrieve a single recipient by ID from your contact database.** + **This endpoint allows you to retrieve a list of all of your subusers.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + You can choose to retrieve specific subusers as well as limit the results that come back from the API. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: username + in: query + description: The username of this subuser. + type: string + - name: limit + in: query + description: The number of results you would like to get in each request. + type: integer + - name: offset + in: query + description: The number of subusers to skip. + type: integer responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_recipient' - '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' - schema: - type: object + 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: '' + description: Unexpected error in API call. See HTTP response body for details. schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - field: null message: authorization required - '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' - schema: - type: object security: - Authorization: [] - delete: - operationId: DELETE_contactdb-recipients-recipient_id - summary: Delete a Recipient + post: + operationId: POST_subusers + summary: Create Subuser tags: - - Contacts API - Recipients - description: |- - **This endpoint allows you to delete a single recipient with the given ID from your contact database.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + - Subusers API + description: '**This endpoint allows you to create a new subuser.**' parameters: - name: body in: body schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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 + example: + username: John@example.com + email: John@example.com + password: johns_password + ips: + - 1.1.1.1 + - 2.2.2.2 responses: - '204': + '200': description: '' schema: - type: object + $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: '"recipient_id" : "Returned if recipient_id is not valid"' + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - - field: null - message: recipient not found + - message: username exists + - message: unable to validate IPs at this time '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - field: null message: authorization required - '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' + '403': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - - field: null - message: recipient_id is not valid + - message: you dont have permission to access this resource + '500': + description: '' + schema: + type: object + examples: + application/json: + errors: + - message: unable to validate IPs at this time security: - Authorization: [] - '/contactdb/recipients/{recipient_id}/lists': + '/subusers/{subuser_name}': parameters: - - name: recipient_id + - name: subuser_name in: path - description: The ID of the recipient for whom you are retrieving lists. required: true type: string - get: - operationId: GET_contactdb-recipients-recipient_id-lists - summary: Retrieve the lists that a recipient is on + patch: + operationId: PATCH_subusers-subuser_name + summary: Enable/disable a subuser tags: - - Contacts API - Recipients - description: |- - **This endpoint allows you to retrieve the lists that a given recipient belongs to.** - - Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to. - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json + - Subusers API + description: '**This endpoint allows you to enable or disable a subuser.**' parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + type: object + properties: + disabled: + type: boolean + description: 'Whether or not this subuser is disabled. True means disabled, False means enabled.' + example: + disabled: false responses: - '200': + '204': description: '' schema: type: object - properties: - lists: - type: array - items: - $ref: '#/definitions/contactdb_list' - examples: - application/json: - lists: - - id: 1234 - name: Example list - recipient_count: 42 + properties: {} '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - - field: null - message: recipient ID is invalid + - message: invalid username + - message: no fields provided '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - field: null message: authorization required - '404': - description: '"recipient_id" : "Returned if record for the recipient id does not exist"' + '500': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - - field: null - message: recipient id not found + - message: unable to enable user security: - Authorization: [] - /contactdb/recipients/billable_count: - get: - operationId: GET_contactdb-recipients-billable_count - summary: Retrieve the count of billable recipients + delete: + operationId: DELETE_subusers-subuser_name + summary: Delete a subuser tags: - - Contacts API - Recipients + - Subusers API description: |- - **This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.** + **This endpoint allows you to delete a subuser.** - You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + This is a permanent action. Once deleted, a subuser cannot be retrieved. responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/contactdb_recipient_count' - examples: - application/json: - recipient_count: 1234 + type: object + properties: {} '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: @@ -4734,236 +4489,179 @@ paths: message: authorization required security: - Authorization: [] - /contactdb/recipients/count: + /subusers/reputations: get: - operationId: GET_contactdb-recipients-count - summary: Retrieve a Count of Recipients + operationId: GET_subusers-reputations + summary: Retrieve Subuser Reputations tags: - - Contacts API - Recipients + - Subusers API description: |- - **This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.** + **This endpoint allows you to request the reputations for your subusers.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - produces: - - application/json + 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 affect your sender rating. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: usernames + in: query + type: string responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_recipient_count' - examples: - application/json: - recipient_count: 1234 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + 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: - errors: - - field: null - message: authorization required + - username: example_subuser + reputation: 99 + - username: example_subuser2 + reputation: 95.2 security: - Authorization: [] - /contactdb/recipients/search: - get: - operationId: GET_contactdb-recipients-search - summary: Retrieve recipients matching search criteria + '/subusers/{subuser_name}/ips': + parameters: + - name: subuser_name + in: path + required: true + type: string + put: + operationId: PUT_subusers-subuser_name-ips + summary: Update IPs assigned to a subuser tags: - - Contacts API - Recipients + - Subusers API description: |- - **This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** + **This endpoint allows you update your subusers' assigned IP.** - field_name: + 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 one or more of their own IP addresses as well. - * 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. + More information: - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - produces: - - application/json + * [How to request more IPs](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/) + * [Setup Reverse DNS](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/) parameters: - - name: '{field_name}' - in: query - type: string - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + type: array + description: The IP addresses you would like to assign to the subuser. + items: + type: string + format: ipv4 + example: + - 127.0.0.1 responses: '200': description: '' schema: type: object properties: - recipients: + ips: type: array + description: The IP addresses that are assigned to the subuser. items: - $ref: '#/definitions/contactdb_recipient' + type: string + format: ipv4 examples: application/json: - recipients: - - created_at: 1422313607 - email: jones@example.com - first_name: null - id: YUBh - last_clicked: null - last_emailed: null - last_name: Jones - last_opened: null - updated_at: 1422313790 - custom_fields: - - id: 23 - name: pet - value: Fluffy - type: text - '400': - description: |- - "" : "Returned if no search params are specified" - "field" : "Returned if the provided field is invalid or does not exist" + ips: + - 127.0.0.1 + '401': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]' - - message: No search params are specified + - field: null + message: authorization required + security: + - Authorization: [] + '/subusers/{subuser_name}/monitor': + parameters: + - name: subuser_name + in: path + description: The name of the subuser for which to retrieve monitor settings. + required: true + type: string + get: + operationId: GET_subusers-subuser_name-monitor + summary: Retrieve monitor settings for a subuser + tags: + - Subuser Monitor Settings + responses: + '200': + description: '' + schema: + $ref: '#/definitions/monitor' + examples: + application/json: + email: example@example.com + frequency: 500 '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - field: null message: authorization required + '404': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: No monitor settings for this user security: - Authorization: [] - /contactdb/segments: post: - operationId: POST_contactdb-segments - summary: Create a Segment + operationId: POST_subusers-subuser_name-monitor + summary: Create monitor settings tags: - - Contacts API - Segments - description: |- - **This endpoint allows you to create a segment.** - - All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment. - - List Id: - - * Send this to segment from an existing list - * Don't send this in order to segment from your entire contactdb. - - Valid operators for create and update depend on the type of the field you are segmenting: - - * **Dates:** "eq", "ne", "lt" (before), "gt" (after) - * **Text:** "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value) - * **Numbers:** "eq", "lt", "gt" - * **Email Clicks and Opens:** "eq" (opened), "ne" (not opened) - - Segment conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either *clicks.campaign_identifier* or *opens.campaign_identifier*. The condition value should be a string containing the id of a completed campaign. - - Segments may contain multiple condtions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or". - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - consumes: - - application/json - produces: - - application/json + - Subuser Monitor Settings parameters: - name: body in: body schema: - $ref: '#/definitions/contactdb_segments' + $ref: '#/definitions/monitor' example: - name: Last Name Miller - list_id: 4 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - - field: last_clicked - value: 01/02/2015 - operator: gt - and_or: and - - field: clicks.campaign_identifier - value: '513' - operator: eq - and_or: or - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + email: example@example.com + frequency: 50000 responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_segments_with_id' + $ref: '#/definitions/monitor' 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 + email: example@example.com + frequency: 50000 '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" + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' 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 + - field: null + message: User already has a monitor '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: @@ -4971,226 +4669,41 @@ paths: message: authorization required security: - Authorization: [] - get: - operationId: GET_contactdb-segments - summary: Retrieve all segments + put: + operationId: PUT_subusers-subuser_name-monitor + summary: Update Monitor Settings for a subuser tags: - - Contacts API - Segments - description: |- - **This endpoint allows you to retrieve all of your segments.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - produces: - - application/json + - Subuser Monitor Settings parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + $ref: '#/definitions/monitor' + example: + email: example@example.com + frequency: 500 responses: '200': description: '' schema: - title: List All Segments response - type: object - properties: - segments: - type: array - items: - $ref: '#/definitions/contactdb_segments' - required: - - segments + $ref: '#/definitions/monitor' examples: application/json: - segments: - - id: 1234 - name: Age segments < 25 - conditions: - - field: age - value: '25' - operator: lt - recipient_count: 8 - - id: 2345 - name: email address - gmail - conditions: - - field: email - value: '@gmail.com' - operator: contains - recipient_count: 0 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - '/contactdb/segments/{segment_id}': - parameters: - - name: segment_id - in: path - required: true - type: string - get: - operationId: GET_contactdb-segments-segment_id - summary: Retrieve a segment - tags: - - Contacts API - Segments - description: |- - **This endpoint allows you to retrieve a single segment with the given ID.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - produces: - - application/json - parameters: - - name: segment_id - in: query - description: The ID of the segment you want to request. - required: true - type: integer - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - patch: - operationId: PATCH_contactdb-segments-segment_id - summary: Update a segment - tags: - - Contacts API - Segments - description: |- - **This endpoint allows you to update a segment.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - 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 - example: - name: The Millers - list_id: 5 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 + email: example@example.com + frequency: 500 '400': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' 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 + - field: email + message: Email is required '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: @@ -5199,1218 +4712,1113 @@ paths: security: - Authorization: [] delete: - operationId: DELETE_contactdb-segments-segment_id - summary: Delete a segment + operationId: DELETE_subusers-subuser_name-monitor + summary: Delete monitor settings tags: - - Contacts API - Segments - description: |- - **This endpoint allows you to delete a segment from your recipients database.** - - You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - produces: - - application/json - parameters: - - name: delete_contacts - in: query - description: True to delete all contacts matching the segment in addition to deleting the segment - type: boolean - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - Subuser Monitor Settings responses: '204': description: '' schema: - type: 'null' - '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 + type: object + properties: {} '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - field: null message: authorization required '404': - description: '"segment_id" : "Returned if segment_id does not exist"' + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - - field: segment_id - message: segment_id does not exist + - field: null + message: No monitor settings for this user security: - Authorization: [] - '/contactdb/segments/{segment_id}/recipients': + '/subusers/{subuser_name}/stats/monthly': parameters: - - name: segment_id + - name: subuser_name in: path - description: The ID of the segment from which you want to retrieve recipients. required: true - type: integer + type: string get: - operationId: GET_contactdb-segments-segment_id-recipients - summary: Retrieve recipients on a segment + operationId: GET_subusers-subuser_name-stats-monthly + summary: Retrieve the monthly email statistics for a single subuser tags: - - Contacts API - Segments + - Subuser Statistics description: |- - **This endpoint allows you to retrieve all of the recipients in a segment with the given ID.** - - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + **This endpoint allows you to retrive the monthly email statistics for a specific subuser.** - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - produces: - - application/json + When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: + `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`. parameters: - - name: page + - name: date in: query + description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD + required: true + type: string + - name: sort_by_metric + in: query + description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.''' + required: false + type: string + default: delivered + - name: sort_by_direction + in: query + description: The direction you want to sort. + required: false + type: string + default: desc + enum: + - desc + - asc + - name: limit + in: query + description: Optional field to limit the number of results returned. + required: false type: integer - - name: page_size + default: 5 + - name: offset in: query + description: Optional beginning point in the list to retrieve from. + required: false type: integer - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + default: 0 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" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - schema: - type: object - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/subuser_stats' examples: application/json: - errors: - - field: null - message: authorization required - '404': - description: |- - "segment_id" : "Returned if segment_id is not valid" - "segment_id" : "Returned if segment_id does not exist" - schema: - type: object + date: '2016-02-01' + stats: + - first_name: John + last_name: Doe + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 5 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 10 + processed: 10 + requests: 10 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: user1 + type: subuser security: - Authorization: [] - /suppression/invalid_emails: + /subusers/stats/monthly: get: - operationId: GET_suppression-invalid_emails - summary: Retrieve all invalid emails + operationId: GET_subusers-stats-monthly + summary: Retrieve monthly stats for all subusers tags: - - Invalid Emails API + - Subuser Statistics description: |- - **This endpoint allows you to retrieve a list of all invalid email addresses.** - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + **This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - produces: - - application/json + When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: + `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`. parameters: - - name: start_time + - name: date in: query - description: Refers start of the time range in unix timestamp when an invalid email was created (inclusive). + description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD + required: true + type: string + - name: subuser + in: query + description: A substring search of your subusers. + required: false + type: string + - name: sort_by_metric + in: query + description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.''' + required: false + type: string + default: delivered + enum: + - blocks + - bounces + - clicks + - delivered + - opens + - requests + - unique_clicks + - unique_opens + - unsubscribes + - name: sort_by_direction + in: query + description: The direction you want to sort. + required: false + type: string + default: desc + enum: + - desc + - asc + - name: limit + in: query + description: Optional field to limit the number of results returned. + required: false type: integer - - name: end_time + default: 5 + - name: offset in: query - description: Refers end of the time range in unix timestamp when an invalid email was created (inclusive). + description: Optional beginning point in the list to retrieve from. + required: false type: integer + default: 0 + responses: + '200': + description: '' + schema: + $ref: '#/definitions/subuser_stats' + examples: + application/json: + date: '2016-02-01' + stats: + - first_name: John + last_name: Doe + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 1 + processed: 0 + requests: 100 + spam_report_drops: 0 + spam_reports: 99 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: user1 + type: subuser + - first_name: Jane + last_name: Doe + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 5 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 10 + processed: 10 + requests: 10 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: user2 + type: subuser + security: + - Authorization: [] + /subusers/stats/sums: + get: + operationId: GET_subusers-stats-sums + summary: Retrieve the totals for each email statistic metric for all subusers. + tags: + - Subuser Statistics + description: '**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**' + parameters: + - name: sort_by_direction + in: query + description: 'The direction you want to sort. ' + required: false + type: string + default: desc + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string - name: limit in: query - description: Limit the number of results to be displayed per page. + description: Limits the number of results returned per page. + required: false type: integer + default: 5 - name: offset in: query - description: Paging offset. The point in the list to begin displaying results. + description: The point in the list to begin retrieving results from. + required: false type: integer - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + default: 0 + - name: aggregated_by + in: query + description: How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string + default: delivered responses: '200': description: '' schema: - type: array - description: The list of invalid email addresses. - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the invalid emails list. - email: - type: string - description: The email address that was marked as invalid. - reason: - type: string - description: The reason that the email address was marked as invalid. - required: - - created - - email - - reason + $ref: '#/definitions/category_stats' examples: application/json: - - created: 1449953655 - email: user1@example.com - reason: Mail domain mentioned in email address is unknown - - created: 1449939373 - email: user1@example.com - reason: Mail domain mentioned in email address is unknown + date: '2015-10-11' + stats: [] security: - Authorization: [] - delete: - operationId: DELETE_suppression-invalid_emails - summary: Delete invalid emails + /subusers/stats: + get: + operationId: GET_subusers-stats + summary: Retrieve email statistics for your subusers. tags: - - Invalid Emails API + - Subuser Statistics description: |- - **This endpoint allows you to remove email addresses from your invalid email address list.** - - There are two options for deleting invalid email addresses: - - 1) You can delete all invalid email addresses by setting `delete_all` to true in the request body. - 2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + **This endpoint allows you to retrieve the email statistics for the given subusers.** - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - delete_all: - type: boolean - description: Indicates if you want to remove all email address from the invalid emails list. - emails: - type: array - description: The list of specific email addresses that you want to remove. - items: - type: string - example: - delete_all: false - emails: - - example1@example.com - - example2@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - '/suppression/invalid_emails/{email}': - parameters: - - name: email - in: path - description: The specific email address of the invalid email entry that you want to retrieve. - required: true - type: string - get: - operationId: GET_suppression-invalid_emails-email - summary: Retrieve a specific invalid email - tags: - - Invalid Emails API - description: |- - **This endpoint allows you to retrieve a specific invalid email addresses.** - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:authorizationHeader:Authorization' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the invalid emails list. - email: - type: string - description: The email address that was marked as invalid. - reason: - type: string - description: A reason explaining why the email address was marked as invalid. - required: - - created - - email - - reason - examples: - application/json: - - created: 1454433146 - email: test1@example.com - reason: Mail domain mentioned in email address is unknown - delete: - operationId: DELETE_suppression-invalid_emails-email - summary: Delete a specific invalid email - tags: - - Invalid Emails API - description: |- - **This endpoint allows you to remove a specific email address from the invalid email address list.** - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:authorizationHeader:Authorization' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - properties: {} - /access_settings/activity: - get: - operationId: GET_access_settings-activity - summary: Retrieve all recent access attempts - tags: - - IP Access Management - description: |- - **This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.** - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - produces: - - application/json + You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser. parameters: - name: limit in: query - description: Limits the number of IPs to return. + description: Limits the number of results returned per page. + required: false type: integer - default: 20 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - type: object - properties: - result: - type: array - items: - type: object - properties: - allowed: - type: boolean - auth_method: - type: string - first_at: - type: integer - ip: - type: string - last_at: - type: integer - location: - type: string - examples: - application/json: - result: - - allowed: false - auth_method: basic - first_at: 1444087966 - ip: 1.1.1.1 - last_at: 1444406672 - location: Australia - security: - - Authorization: [] - /access_settings/whitelist: - get: - operationId: GET_access_settings-whitelist - summary: Retrieve a list of currently whitelisted IPs - tags: - - IP Access Management - description: |- - **This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.** - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - 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: - type: object - properties: - result: - type: array - description: An array listing all of your whitelisted IPs. - items: - type: object - properties: - id: - type: integer - description: The ID of the whitelisted IP. - ip: - type: string - description: The whitelisted IP. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IPs whitelisting status was most recently updated. - required: - - id - - ip - - created_at - - updated_at - required: - - result + $ref: '#/definitions/stats' examples: application/json: - result: - - id: 1 - ip: 192.168.1.1/32 - created_at: 1441824715 - updated_at: 1441824715 - - id: 2 - ip: 192.168.1.2/32 - created_at: 1441824715 - updated_at: 1441824715 - - id: 3 - ip: 192.168.1.3/32 - created_at: 1441824715 - updated_at: 1441824715 - security: - - Authorization: [] - post: - operationId: POST_access_settings-whitelist - summary: Add one or more IPs to the whitelist - tags: - - IP Access Management - description: |- - **This endpoint allows you to add one or more IP addresses to your IP whitelist.** - - When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - ips: - type: array - description: An array containing the IP(s) you want to whitelist. - items: - type: object - properties: - ip: - type: string - description: An IP address that you want to whitelist. - required: - - ip - required: - - ips - example: - ips: - - ip: 192.168.1.1 - - ip: 192.*.*.* - - ip: 192.168.1.3/32 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '201': - description: '' - schema: - type: object - properties: - result: - type: array - description: An array listing all of your whitelisted IPs. - items: - type: object - properties: - id: - type: integer - description: The ID of the whitelisted IP. - ip: - type: string - description: The whitelisted IP. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IPs whitelisting status was most recently updated. - required: - - id - - ip - - created_at - - updated_at - required: - - result - examples: - application/json: - result: - - id: 1 - ip: 192.168.1.1/32 - created_at: 1441824715 - updated_at: 1441824715 - - id: 2 - ip: 192.0.0.0/8 - created_at: 1441824715 - updated_at: 1441824715 - - id: 3 - ip: 192.168.1.3/32 - created_at: 1441824715 - updated_at: 1441824715 + - date: '2015-10-01' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-02' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-03' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-04' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-05' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-06' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-07' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-08' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-09' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-10' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 security: - Authorization: [] - delete: - operationId: DELETE_access_settings-whitelist - summary: Remove one or more IPs from the whitelist + /whitelabel/links: + post: + operationId: POST_whitelabel-links + summary: Create a branded link tags: - - IP Access Management + - Link branding description: |- - **This endpoint allows you to remove one or more IPs from your IP whitelist.** - - You can remove one IP at a time, or you can remove multiple IP addresses. + **This endpoint allows you to create a new branded link.** - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + To create the link branding, supply the root domain and, optionally, the subdomain — these go into separate fields in your request body. The root domain should match your FROM email address. If you provide a subdomain, it must be different from the subdomain you used for authenticating your domain. - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - produces: - - application/json + You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. parameters: - name: body in: body schema: type: object properties: - ids: - type: array - description: An array of the IDs of the IP address that you want to remove from your whitelist. - items: - type: integer - example: - ids: - - 1 - - 2 - - 3 + domain: + type: string + description: The root domain for the subdomain that you are creating the link branding for. This should match your FROM email address. + subdomain: + type: string + description: The subdomain to create the link branding for. Must be different from the subdomain you used for authenticating your domain. + default: + type: boolean + description: 'Indicates if you want to use this link branding as the default or fallback. When setting a new default, the existing default link branding will have its default status removed automatically.' + enum: + - true + - false + required: + - domain + example: + domain: example.com + subdomain: mail + default: true - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': + '201': description: '' schema: - type: object - properties: {} + $ref: '#/definitions/link_branding_200_response' + examples: + application/json: + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - '/access_settings/whitelist/{rule_id}': - parameters: - - name: rule_id - in: path - description: The ID of the whitelisted IP address that you want to retrieve. - required: true - type: string get: - operationId: GET_access_settings-whitelist-rule_id - summary: Retrieve a specific whitelisted IP + operationId: GET_whitelabel-links + summary: Retrieve all branded links tags: - - IP Access Management + - Link branding description: |- - **This endpoint allows you to retreive a specific IP address that has been whitelisted.** - - You must include the ID for the specific IP address you want to retrieve in your call. + **This endpoint allows you to retrieve all branded links**. - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - produces: - - application/json + You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. parameters: + - name: limit + in: query + description: Limits the number of results returned per page. + type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - id: - type: integer - description: The ID of the IP address. - ip: - type: string - description: The IP address. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IP address was last updated. - required: - - id - - ip - - created_at - - updated_at + type: array + items: + $ref: '#/definitions/link_branding_200_response' examples: application/json: - id: 1 - ip: 192.168.1.1 - created_at: 1441824715 - updated_at: 1441824715 + - id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: true + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + - id: 2 + domain: example2.com + subdomain: news + username: john@example.com + user_id: 8 + default: false + valid: false + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: news.example2.com + data: sendgrid.net + owner_cname: + valid: false + type: cname + host: 8.example2.com + data: sendgrid.net security: - Authorization: [] - delete: - operationId: DELETE_access_settings-whitelist-rule_id - summary: Remove a specific IP from the whitelist + '/whitelabel/links/{id}/validate': + parameters: + - name: id + in: path + description: The ID of the branded link that you want to validate. + required: true + type: integer + post: + operationId: POST_whitelabel-links-id-validate + summary: Validate a branded link tags: - - IP Access Management + - Link branding description: |- - **This endpoint allows you to remove a specific IP address from your IP whitelist.** - - When removing a specific IP address from your whitelist, you must include the ID in your call. + **This endpoint allows you to validate a branded link.** - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. parameters: - - name: body - in: body - schema: - type: 'null' - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': + '200': description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - /ips: - post: - operationId: POST_ips - summary: Add IPs - tags: - - IP Addresses - description: This endpoint is for adding a(n) IP Address(es) to your account. - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body schema: type: object properties: - count: + id: type: integer - description: The amount of IPs to add to the account. - subusers: - type: array - description: Array of usernames to be assigned a send IP. - items: - type: string - warmup: + description: The ID of the branded link. + valid: type: boolean - default: false - description: Whether or not to warmup the IPs being added. + description: Indicates if the link branding is valid. + enum: + - true + - false + validation_results: + type: object + description: The individual validation results for each of the DNS records associated with this branded link. + required: + - domain_cname + properties: + domain_cname: + type: object + description: The DNS record generated for the sending domain used for this branded link. + required: + - valid + - reason + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + enum: + - true + - false + reason: + type: string + nullable: true + 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 branded link. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + enum: + - true + - false + reason: + type: string + nullable: true + description: 'Null if valid. If the DNS record is invalid, this will explain why.' + required: + - valid + - reason required: - - count - example: - count: 90323478 - subusers: - - subuser1 - - subuser2 - warmup: true - user_can_send: true - responses: - '201': + - id + - valid + - validation_results + examples: + application/json: + id: 1 + valid: true + validation_results: + domain_cname: + valid: false + reason: Expected CNAME to match "sendgrid.net." but found "example.com.". + owner_cname: + valid: true + reason: null + '500': description: '' schema: type: object properties: - ips: + errors: type: array - description: List of IP objects. + description: The reasons why the validation failed. items: type: object properties: - ip: + message: type: string - description: IP added to account. - subusers: - type: array - description: Array of usernames assigned a send IP. - items: - type: string + description: The reason why the link whitelabel could not be validated. required: - - ip - - subusers - remaining_ips: - type: integer - description: The number of IPs that can still be added to the user. - warmup: - type: boolean - description: Whether or not the IPs are being warmed up. + - message required: - - ips - - remaining_ips - - warmup - examples: - application/json: - ips: - - ip: 1.2.3.4 - subusers: - - user - - subuser1 - - ip: 1.2.3.5 - subusers: - - user - - subuser1 - remaining_ips: 1 - warmup: true - '400': - description: '' - schema: - $ref: '#/definitions/errors' + - errors examples: application/json: errors: - - field: null - message: one or more subusers do not belong to this user + - message: internal error getting CNAME security: - Authorization: [] - get: - operationId: GET_ips - summary: Retrieve all IP addresses + '/whitelabel/links/{link_id}/subuser': + parameters: + - name: link_id + in: path + description: The ID of the branded link you want to associate. + required: true + type: integer + post: + operationId: POST_whitelabel-links-link_id-subuser + summary: Associate a branded link with a subuser tags: - - IP Addresses + - Link branding description: |- - **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** - - Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. + **This endpoint allows you to associate a branded link with a subuser account.** - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - produces: - - application/json + Link branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers). 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: limit - in: query - description: The number of IPs you want returned at the same time. - type: integer - default: 10 - - name: offset - in: query - description: The offset for the number of IPs that you are requesting. - type: integer - default: 0 - - name: subuser - in: query - description: The subuser you are requesting for. - type: string - - name: sort_by_direction - in: query - description: The direction to sort the results. - type: string - enum: - - desc - - asc + - name: body + in: body + schema: + type: object + properties: + username: + type: string + description: The username of the subuser account that you want to associate the branded link with. + example: + username: jane@example.com responses: '200': description: '' schema: - type: array - items: - type: object - properties: - ip: - type: string - description: An IP address. - subusers: - type: array - description: The subusers that are able to send email from this IP. - items: - type: string - rdns: - type: string - description: The reverse DNS record for this IP address. - pools: - type: array - description: The IP pools that this IP has been added to. - items: - type: string - warmup: - type: boolean - description: Indicates if this IP address is currently warming up. - start_date: - type: - - number - - 'null' - description: The date that the IP address was entered into warmup. - whitelabeled: - type: boolean - description: Indicates if this IP address has been whitelabeled. - assigned_at: - type: - - integer - - 'null' - description: The date that the IP address was assigned to the user. - required: - - ip - - subusers - - pools - - warmup - - start_date - - whitelabeled - - assigned_at + $ref: '#/definitions/link_branding_200_response' examples: application/json: - - ip: 192.168.1.1 - pools: - - pool1 - - pool2 - whitelabeled: false - start_date: 1409616000 - subusers: - - tim@sendgrid.net - warmup: false - assigned_at: 1482883200 - - ip: 208.115.214.22 - pools: [] - whitelabeled: true - rdns: o1.email.burgermail.com - start_date: 1409616000 - subusers: [] - warmup: false - assigned_at: 1482883200 + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - /ips/remaining: + '/whitelabel/links/{id}': + parameters: + - name: id + in: path + description: The ID of the branded link you want to retrieve. + required: true + type: integer get: - operationId: GET_ips-remaining - summary: Get remaining IPs count + operationId: GET_whitelabel-links-id + summary: Retrieve a branded link tags: - - IP Addresses - description: This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs. - produces: - - application/json + - Link branding + description: |- + **This endpoint allows you to retrieve a specific branded link by providing its ID.** + + You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - results: - type: array - items: - type: object - properties: - remaining: - type: integer - description: The number of IPs that can still be added to the user. - period: - type: string - description: The length of time until user can add more IPs. - price_per_ip: - type: number - description: The current cost to add an IP. - required: - - remaining - - period - - price_per_ip - required: - - results + $ref: '#/definitions/link_branding_200_response' examples: application/json: - results: - - remaining: 2 - period: month - price_per_ip: 20 + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - /ips/assigned: - get: - operationId: GET_ips-assigned - summary: Retrieve all assigned IPs + patch: + operationId: PATCH_whitelabel-links-id + summary: Update a branded link tags: - - IP Addresses + - Link branding description: |- - **This endpoint allows you to retrieve only assigned IP addresses.** + **This endpoint allows you to update a specific branded link. You can use this endpoint to change a branded link's default status.** - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - produces: - - application/json + You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. + parameters: + - name: body + in: body + schema: + type: object + properties: + default: + type: boolean + description: 'Indicates if the branded link is set as the default. When setting a new default, the existing default link branding will have its default status removed automatically.' + enum: + - true + - false + example: + default: true + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - title: List all assigned IPs response - items: - type: object - properties: - ip: - type: string - description: The IP address. - pools: - type: array - description: The IP pools that this IP address has been added to. - items: - type: string - warmup: - type: boolean - description: Indicates if this IP address is currently warming up. - start_date: - type: integer - description: The start date that this IP address was entered into warmup. - required: - - ip - - pools - - warmup - - start_date + $ref: '#/definitions/link_branding_200_response' examples: application/json: - - ip: 167.89.21.3 - pools: - - new_test5 - warmup: true - start_date: 1409616000 + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: true + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - '/ips/{ip_address}': - parameters: - - name: ip_address - in: path - description: The IP address you are retrieving the IP pools for. - required: true - type: string - get: - operationId: GET_ips-ip_address - summary: Retrieve all IP pools an IP address belongs to + delete: + operationId: DELETE_whitelabel-links-id + summary: Delete a branded link tags: - - IP Addresses + - Link branding description: |- - **This endpoint allows you to see which IP pools a particular IP address has been added to.** + **This endpoint allows you to delete a branded link.** - The same IP address can be added to multiple IP pools. + Your request will receive a response with a 204 status code if the deletion was successful. The call does not return the link's details, so if you wish to record these make sure you call the #endpoint:9Rjrfftdm4Jdzqpko endpoint *before* you request its deletion. - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - produces: - - application/json + You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' schema: type: object - properties: - ip: - type: string - description: The IP address. - subusers: - type: array - description: The subusers that can send email using this IP address. - items: - type: string - rdns: - type: string - description: The reverse DNS record for this IP address. - pools: - type: array - description: The list of IP pools that this IP address belongs to. - items: - type: string - warmup: - type: boolean - description: Indicates if this IP address is currently warming up. - start_date: - type: - - integer - - 'null' - description: The date that the IP address was entered into warmup. - whitelabeled: - type: boolean - description: Indicates if this IP address has been whitelabeled. - required: - - ip - - subusers - - rdns - - pools - - warmup - - start_date - - whitelabeled - examples: - application/json: - ip: 000.00.00.0 - subusers: - - subuser1 - - subuser2 - rdns: o1.em.example.com - pools: - - test1 - warmup: false - start_date: null - whitelabeled: true security: - Authorization: [] - /ips/pools: - post: - operationId: POST_ips-pools - summary: Create an IP pool. + /whitelabel/links/default: + get: + operationId: GET_whitelabel-links-default + summary: Retrieve the default branded link tags: - - IP Pools + - Link branding description: |- - **This endpoint allows you to create an IP pool.** + **This endpoint allows you to retrieve the default branded link.** - **Each user can create up to 10 different IP pools.** + The default branded link is the actual URL to be used when sending messages. If you have more than one branded link, the default is determined by the following order: - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + * The validated branded link marked as `default` (set when you call #endpoint:2gXQQ3udkNjXHWjmk or by calling #endpoint:Hx235Zi3nPGGtpNdM on an existing link) + * Legacy branded links (migrated from the whitelabel wizard) + * Default SendGrid-branded links (i.e., `100.ct.sendgrid.net`) - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - consumes: - - application/json - produces: - - application/json + You can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request. parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - description: The name of your new IP pool. - maxLength: 64 - required: - - name - example: - name: marketing + - name: domain + in: query + description: The domain to match against when finding the default branded link. + type: string + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/ip_pool' + $ref: '#/definitions/link_branding_200_response' examples: application/json: - name: marketing + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] + /whitelabel/links/subuser: get: - operationId: GET_ips-pools - summary: Retrieve all IP pools. + operationId: GET_whitelabel-links-subuser + summary: Retrieve a subuser's branded link tags: - - IP Pools + - Link branding description: |- - **This endpoint allows you to retreive all of your IP pools.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + **This endpoint allows you to retrieve the branded link associated with a subuser.** - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - produces: - - application/json + Link branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and then validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers). + parameters: + - name: username + in: query + description: The username of the subuser to retrieve associated branded links for. + required: true + type: string responses: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/ip_pool' + $ref: '#/definitions/link_branding_200_response' examples: application/json: - - name: marketing - - name: transactional + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net security: - Authorization: [] - '/ips/pools/{pool_name}': - parameters: - - name: pool_name - in: path - description: The name of the IP pool that you want to retrieve the IP addresses from. - required: true - type: string - get: - operationId: GET_ips-pools-pool_name - summary: Retrieve all IPs in a specified pool. + delete: + operationId: DELETE_whitelabel-links-subuser + summary: Disassociate a branded link from a subuser tags: - - IP Pools + - Link branding description: |- - **This endpoint allows you to list all of the IP addresses that are in a specific IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + **This endpoint allows you to take a branded link away from a subuser.** - IP pools can only be used with whitelabeled IP addresses. + Link branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers). - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - produces: - - application/json + Your request will receive a response with a 204 status code if the disassociation was successful. + parameters: + - name: username + in: query + description: The username of the subuser account that you want to disassociate a branded link from. + required: true + type: string responses: - '200': - description: '' - schema: - type: object - properties: - pool_name: - type: string - description: The name of the IP pool. - maxLength: 64 - ips: - type: array - description: The list of IP addresses that belong to this IP pool. - items: - type: string - required: - - pool_name - '404': + '204': description: '' schema: type: object - properties: - errors: - type: array - items: - type: object - properties: - field: - type: string - description: The name of the error. - message: - type: string - description: A message explaining why the IP addresses could not be listed. - examples: - application/json: - errors: - - field: error - message: Unable to locate specified IPs Pool security: - Authorization: [] - put: - operationId: PUT_ips-pools-pool_name - summary: Update an IP pool’s name. + /ips/warmup: + post: + operationId: POST_ips-warmup + summary: Start warming up an IP address tags: - - IP Pools - description: |- - **This endpoint allows you to update the name of an IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - consumes: - - application/json - produces: - - application/json + - IP Warmup + description: '**This endpoint allows you to put an IP address into warmup mode.**' parameters: - name: body in: body schema: type: object properties: - name: + ip: type: string - description: The new name for your IP pool. - maxLength: 64 + description: The IP address that you want to begin warming up. example: - name: new_pool_name + ip: 0.0.0.0 responses: '200': description: '' schema: - $ref: '#/definitions/ip_pool' + $ref: '#/definitions/ip_warmup_response' examples: application/json: - name: new_pool_name + - ip: 0.0.0.0 + start_date: 1409616000 '404': description: '' schema: @@ -6418,6 +5826,7 @@ paths: properties: errors: type: array + description: The errors that were encountered. items: type: object properties: @@ -6425,133 +5834,7 @@ paths: type: 'null' message: type: string - description: A message explaining why the name of your IP pool could not be updated. - examples: - application/json: - errors: - - field: null - message: ip pool not found - security: - - Authorization: [] - delete: - operationId: DELETE_ips-pools-pool_name - summary: Delete an IP pool. - tags: - - IP Pools - description: |- - **This endpoint allows you to delete an IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - '404': - description: '' - schema: - type: object - properties: - error: - type: string - description: An error explaining why the pool could not be deleted. - examples: - application/json: - error: Unable to locate specified IPs Pool - security: - - Authorization: [] - '/ips/pools/{pool_name}/ips': - parameters: - - name: pool_name - in: path - description: The name of the IP pool that you want to add an IP address to. - required: true - type: string - post: - operationId: POST_ips-pools-pool_name-ips - summary: Add an IP address to a pool - tags: - - IP Pools - description: |- - **This endpoint allows you to add an IP address to an IP pool.** - - You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - ip: - type: string - description: The IP address that you want to add to an IP pool. - example: - ip: 0.0.0.0 - responses: - '201': - description: '' - schema: - type: object - properties: - ip: - type: string - description: The IP address. - pools: - type: array - description: The list of IP pools that this IP address has been added to. - items: - type: string - start_date: - type: integer - description: A unix timestamp indicating when the warmup process began for the IP address. - warmup: - type: boolean - description: Indicates if the IP address is in warmup. - required: - - ip - - pools - - start_date - - warmup - examples: - application/json: - ip: 000.00.00.0 - pools: - - test1 - start_date: 1409616000 - warmup: true - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The error returned. - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the IP address could not be added to the IP Pool. + description: A message explaining why the IP couldn't entered into warmup mode. examples: application/json: errors: @@ -6559,108 +5842,12 @@ paths: message: resource not found security: - Authorization: [] - '/ips/pools/{pool_name}/ips/{ip}': - parameters: - - name: pool_name - in: path - description: The name of the IP pool that you are removing the IP address from. - required: true - type: string - - name: ip - in: path - description: The IP address that you are removing. - required: true - type: string - delete: - operationId: DELETE_ips-pools-pool_name-ips-ip - summary: Remove an IP address from a pool. - tags: - - IP Pools - description: |- - **This endpoint allows you to remove an IP address from an IP pool.** - - The same IP address can be added to multiple IP pools. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - responses: - '204': - description: '' - schema: - type: object - '404': - description: '' - schema: - type: object - properties: - error: - type: string - description: An error explaining why the IP address could not be removed from the IP pool. - examples: - application/json: - error: Unable to locate specified IPs Pool - security: - - Authorization: [] - /ips/warmup: get: operationId: GET_ips-warmup summary: Retrieve all IPs currently in warmup tags: - IP Warmup - description: |- - **This endpoint allows you to retrieve all of your IP addresses that are currently warming up.** - - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - $ref: '#/definitions/ip_warmup_response' - examples: - application/json: - - ip: 0.0.0.0 - start_date: 1409616000 - security: - - Authorization: [] - post: - operationId: POST_ips-warmup - summary: Add an IP to warmup - tags: - - IP Warmup - description: |- - **This endpoint allows you to enter an IP address into warmup mode.** - - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - 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 begin warming up. - example: - ip: 0.0.0.0 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + description: '**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**' responses: '200': description: '' @@ -6670,27 +5857,6 @@ paths: application/json: - ip: 0.0.0.0 start_date: 1409616000 - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The errors that were encountered. - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the IP couldn't entered into warmup mode. - examples: - application/json: - errors: - - field: null - message: resource not found security: - Authorization: [] '/ips/warmup/{ip_address}': @@ -6702,24 +5868,22 @@ paths: type: string get: operationId: GET_ips-warmup-ip_address - summary: Retrieve warmup status for a specific IP address + summary: Retrieve the warmup status for a specific IP address tags: - IP Warmup description: |- **This endpoint allows you to retrieve the warmup status for a specific IP address.** - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + You can retrieve all of your warming IPs using the #endpoint:T8KgmGqsDsx9JTHp8 endpoint. responses: '200': description: '' schema: $ref: '#/definitions/ip_warmup_response' + examples: + application/json: + - ip: 0.0.0.0 + start_date: 1409616000 '404': description: '' schema: @@ -6745,23 +5909,13 @@ paths: - Authorization: [] delete: operationId: DELETE_ips-warmup-ip_address - summary: Remove an IP from warmup + summary: Stop warming up an IP address tags: - IP Warmup description: |- **This endpoint allows you to remove an IP address from warmup mode.** - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + Your request will return a 204 status code if the specified IP was successfully removed from warmup mode. To retrieve details of the IP’s warmup status *before* removing it from warmup mode, call the #endpoint:qf84mxELWH3Prd9JB endpoint. responses: '204': description: '' @@ -6790,402 +5944,299 @@ paths: message: resource not found security: - Authorization: [] - /senders: + /whitelabel/ips: post: - operationId: POST_senders - summary: Create a Sender Identity + operationId: POST_whitelabel-ips + summary: Set up reverse DNS tags: - - Sender Identities API - description: |- - **This endpoint allows you to create a new sender identity.** - - *You may create up to 100 unique sender identities.* - - Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`. - consumes: - - application/json - produces: - - application/json + - Reverse DNS + description: '**This endpoint allows you to set up reverse DNS.**' parameters: - name: body in: body schema: type: object properties: - nickname: + ip: type: string - description: A nickname for the sender identity. Not used for sending. - from: - type: object - properties: - email: - type: string - description: This is where the email will appear to originate from for your recipient - name: - type: string - description: This is the name appended to the from email field. IE - Your name or company name. - required: - - email - reply_to: - type: object - properties: - email: - type: string - description: This is the email that your recipient will reply to. - name: - type: string - description: This is the name appended to the reply to email field. IE - Your name or company name. - required: - - email - address: - type: string - description: The physical address of the sender identity. - address_2: - type: string - description: Additional sender identity address information. - city: - type: string - description: The city of the sender identity. - state: - type: string - description: The state of the sender identity. - zip: + description: The IP address for which you want to set up reverse DNS. + subdomain: type: string - description: The zipcode of the sender identity. - country: + description: The subdomain that will be used to send emails from the IP address. This should be the same as the subdomain used to set up an authenticated domain. + domain: type: string - description: The country of the sender identity. + description: 'The root, or sending, domain that will be used to send message from the IP address.' required: - - nickname - - address - - city - - country + - ip + - domain example: - nickname: My Sender ID - from: - email: from@example.com - name: Example INC - reply_to: - email: replyto@example.com - name: Example INC - address: 123 Elm St. - address_2: Apt. 456 - city: Denver - state: Colorado - zip: '80202' - country: United States + ip: 192.168.1.1 + subdomain: email + domain: example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '201': description: '' schema: - $ref: '#/definitions/senderID' - examples: - application/json: - id: 1 - nickname: My Sender ID - from: - email: from@example.com - name: Example INC - reply_to: - email: replyto@example.com - name: Example INC - address: 123 Elm St. - address_2: Apt. 456 - city: Denver - state: Colorado - zip: '80202' - country: United States - verified: true - updated_at: 1449872165 - created_at: 1449872165 - locked: false - '400': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string + $ref: '#/definitions/reverse_dns' examples: application/json: - errors: - - message: The JSON you have submitted cannot be parsed. - field: '' - - message: You've reached your limit of 100 sender identities. Please delete one or more and try again. - field: '' - - message: nickname is required. - field: nickname - - message: You already have a sender identity with the same nickname. - field: nickname - - message: from_name is required. - field: from_name - - message: from_email is required. - field: from_email - - message: From email is not a valid email address. - field: from_email - - message: reply_to is required. - field: reply_to - - message: Reply to email is not a valid email address. - field: reply_to - - message: address is required. - field: address - - message: city is required. - field: city - - message: country is required. - field: country + 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 security: - Authorization: [] get: - operationId: GET_v3-senders - summary: Get all Sender Identities + operationId: GET_whitelabel-ips + summary: Retrieve all reverse DNS records tags: - - Sender Identities API + - Reverse DNS description: |- - **This endpoint allows you to retrieve a list of all sender identities that have been created for your account.** + **This endpoint allows you to retrieve all of the Reverse DNS records created by this account.** - Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`. - produces: - - application/json + You may include a search key by using the `ip` query string parameter. This enables you to perform a prefix search for a given IP segment (e.g., `?ip="192."`). + + Use the `limit` query string parameter to reduce the number of records returned. All records will be returned if you have fewer records than the specified limit. + + The `offset` query string parameter allows you to specify a non-zero index from which records will be returned. For example, if you have ten records, `?offset=5` will return the last five records (at indexes 5 through 9). The list starts at index zero. parameters: + - name: limit + in: query + description: The maximum number of results to retrieve. + type: integer + - name: offset + in: query + description: The point in the list of results to begin retrieving IP addresses from. + type: integer + - name: ip + in: query + description: The IP address segment that you'd like to use in a prefix search. + type: string - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - result: - type: array - items: - $ref: '#/definitions/senderID' + type: array + items: + $ref: '#/definitions/reverse_dns' examples: application/json: - result: - - id: 1 - nickname: My Sender ID - from: - email: from@example.com - name: Example INC - reply_to: - email: replyto@example.com - name: Example INC - address: 123 Elm St. - address_2: Apt. 456 - city: Denver - state: Colorado - zip: '80202' - country: United States - verified: true - updated_at: 1449872165 - created_at: 1449872165 - locked: false + - 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 security: - Authorization: [] - '/senders/{sender_id}': + '/whitelabel/ips/{id}/validate': parameters: - - name: sender_id + - name: id in: path - description: The ID of the sender identity that you want to update. + description: The ID of the reverse DNS record that you would like to validate. required: true - type: integer - patch: - operationId: PATCH_v3-senders-sender_id - summary: Update a Sender Identity + type: string + post: + operationId: POST_whitelabel-ips-id-validate + summary: Validate a reverse DNS record tags: - - Sender Identities API + - Reverse DNS description: |- - **This endpoint allows you to update a sender identity.** + **This endpoint allows you to validate a reverse DNS record.** - Updates to `from.email` require re-verification. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`. + Always check the `valid` property of the response’s `validation_results.a_record` object. This field will indicate whether it was possible to validate the reverse DNS record. If the `validation_results.a_record.valid` is `false`, this indicates only that Twilio SendGrid could not determine the validity your reverse DNS record — it may still be valid. - Partial updates are allowed, but fields that are marked as "required" in the POST (create) endpoint must not be nil if that field is included in the PATCH request. - consumes: - - application/json - produces: - - application/json + If validity couldn’t be determined, you can check the value of `validation_results.a_record.reason` to find out why. + + You can retrieve the IDs associated with all your reverse DNS records using the "#endpoint:ZqgmCfzjZqJYaava7" endpoint. parameters: - - name: body - in: body + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' schema: type: object properties: - nickname: - type: string - description: A nickname for the sender identity. Not used for sending. - from: + id: + type: integer + description: The ID of the reverse DNS record. + valid: + type: boolean + description: Indicates if the reverse DNS record is valid. + enum: + - true + - false + validation_results: type: object + description: The specific results of the validation. properties: - email: - type: string - description: This is where the email will appear to originate from for your recipient - name: - type: string - description: This is the name appended to the from email field. IE - Your name or company name. - reply_to: - type: object - properties: - email: - type: string - description: This is the email that your recipient will reply to. - name: - type: string - description: This is the name appended to the reply to email field. IE - Your name or company name. - address: - type: string - description: The physical address of the sender identity. - address_2: - type: string - description: Additional sender identity address information. - city: - type: string - description: The city of the sender identity. - state: - type: string - description: The state of the sender identity. - zip: - type: string - description: The zipcode of the sender identity. - country: - type: string - description: The country of the sender identity. - example: - nickname: My Sender ID - from: - email: from@example.com - name: Example INC - reply_to: - email: replyto@example.com - name: Example INC - address: 123 Elm St. - address_2: Apt. 456 - city: Denver - state: Colorado - zip: '80202' - country: United States - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - $ref: '#/definitions/senderID' + a_record: + type: object + properties: + valid: + type: boolean + description: Indicates if the reverse DNS record could be validated. + enum: + - true + - false + reason: + type: + - 'null' + - string + description: The reason the reverse DNS record could not be validated. Is `null` if the reverse DNS record was validated. + required: + - valid + - reason + required: + - id + - valid + - validation_results examples: application/json: - id: 1 - nickname: My Sender ID - from: - email: from@example.com - name: Example INC - reply_to: - email: replyto@example.com - name: Example INC - address: 123 Elm St. - address_2: Apt. 456 - city: Denver - state: Colorado - zip: '80202' - country: United States - verified: true - updated_at: 1449872165 - created_at: 1449872165 - locked: false - '400': - description: '' + id: 123456 + valid: false + validation_results: + a_record: + valid: false + reason: 'Failed to resolve A Record at o1.ptr4283.example.com: lookup o1.ptr4283.example.com on 192.168.0.10:53: no such host' + '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 - field: - type: string + description: A message describing why the reverse DNS could not be validated. + required: + - message + required: + - errors examples: application/json: errors: - - message: The JSON you have submitted cannot be parsed. - field: '' - - message: nickname is required. - field: nickname - - message: You already have a sender identity with the same nickname. - field: nickname - - message: from_name is required. - field: from_name - - message: from_email is required. - field: from_email - - message: From email is not a valid email address. - field: from_email - - message: reply_to is required. - field: reply_to - - message: Reply to email is not a valid email address. - field: reply_to - - message: address is required. - field: address - - message: city is required. - field: city - - message: country is required. - field: country - '403': + - message: Reverse DNS record 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 - field: - type: string + description: A message describing why the IP whitelabel could not be validated. + required: + - message + required: + - errors examples: application/json: errors: - - message: You may only update a sender identity when it is unlocked. - field: locked - '404': + - message: internal error getting rDNS + security: + - Authorization: [] + '/whitelabel/ips/{id}': + parameters: + - name: id + in: path + description: The ID of the reverse DNS record that you would like to retrieve. + required: true + type: string + get: + operationId: GET_whitelabel-ips-id + summary: Retrieve a reverse DNS record + tags: + - Reverse DNS + description: |- + **This endpoint allows you to retrieve a reverse DNS record.** + + You can retrieve the IDs associated with all your reverse DNS records using the "#endpoint:ZqgmCfzjZqJYaava7" endpoint. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string + $ref: '#/definitions/reverse_dns' examples: application/json: - errors: - - message: resource not found - field: id + 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 security: - Authorization: [] delete: - operationId: DELETE_v3-senders-sender_id - summary: Delete a Sender Identity + operationId: DELETE_whitelabel-ips-id + summary: Delete a reverse DNS record tags: - - Sender Identities API + - Reverse DNS description: |- - **This endoint allows you to delete one of your sender identities.** + **This endpoint allows you to delete a reverse DNS record.** - Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`. - produces: - - application/json + A call to this endpoint will respond with a 204 status code if the deletion was successful. + + You can retrieve the IDs associated with all your reverse DNS records using the "#endpoint:ZqgmCfzjZqJYaava7" endpoint. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: @@ -7193,151 +6244,403 @@ paths: description: '' schema: type: object - properties: {} - '403': + security: + - Authorization: [] + /validations/email: + post: + operationId: POST_validations-email + summary: Validate an email + tags: + - Email Address Validation + description: '**This endpoint allows you to validate an email address.**' + parameters: + - name: body + in: body + schema: + type: object + properties: + email: + type: string + description: The email address that you want to validate. + source: + type: string + description: An optional indicator of the email address's source. You may include this if you are capturing email addresses from multiple locations. + required: + - email + example: + email: example@example.com + source: Signup Form + responses: + '200': description: '' schema: type: object properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string + result: + type: object + properties: + email: + type: string + format: email + description: The email address being validated. + verdict: + type: string + enum: + - Valid + - Risky + - Invalid + description: 'This field will contain one of three categories: “Valid”, “Risky”, or “Invalid”. These are generic classifications based on the detailed results. You can filter based on this field, but you can also look at more detailed information available in the `score` and `checks` fields.' + score: + type: number + minimum: 0 + maximum: 1 + description: This number from 0 to 1 represents the likelihood the email address is valid. Scores closer to 1 are more likely to be valid. + local: + type: string + description: The local portion of an email address is everything before the @ symbol. + host: + type: string + description: the domain following the @ symbol in an email address. + suggestion: + type: string + description: 'If Twilio SendGrid detects what it believes to be a typo in the address''s domain, it will provide a suggested correct spelling in this field.' + checks: + type: object + description: A list of all the checks that ran on the email address. You can use these results to determine your own standards for the message's validity. + properties: + domain: + type: object + description: 'The checks performed on the domain portion, after the @ symbol, of the email address.' + properties: + has_valid_address_syntax: + type: boolean + description: Indicates if the domain is properly formatted. + has_mx_or_a_record: + type: boolean + description: Indicates if the domain has appropriate DNS records needed for email receipt and delivery. + is_suspected_disposable_address: + type: boolean + description: Indicates if the email address's domain appears to be from a disposable email address service. + local_part: + type: object + description: 'The checks performed on the local portion, before the @ symbol, of the email address.' + properties: + is_suspected_role_address: + type: boolean + description: 'Indicates if the local portion of the email appears to be a group address such as "hr," "support," or "admin."' + additional: + type: object + description: Additional checks performed on the address. + properties: + has_known_bounces: + type: boolean + description: Indicates if the address has previously bounced a message sent by Twilio SendGrid. + has_suspected_bounces: + type: boolean + description: Indicates if Twilio SendGrid's machine learning suspects the address will bounce. + source: + type: string + description: An optional indicator of the email address's source. You may include this if you are capturing email addresses from multiple locations. + ip_address: + type: string + description: The IP address the validation request was made from. examples: application/json: - errors: - - message: You may only delete a sender identity when it is unlocked. - field: locked - '404': - description: '' + result: + email: jane_doe@gmial.com + verdict: Valid + score: 0.79498 + local: jane_doe + host: gmial.com + suggestion: gmail.com + checks: + domain: + has_valid_address_syntax: true + has_mx_or_a_record: true + is_suspected_disposable_address: false + local_part: + is_suspected_role_address: false + additional: + has_known_bounces: false + has_suspected_bounces: true + ip_address: 192.168.2.1 + security: + - Authorization: [] + /validations/email/bulk: + post: + operationId: POST_validations-email-bulk + summary: Validate a list of Email Addresses + tags: + - Email Address Validation + description: '**This endpoint allows you to validate a list of email addresses.**' + parameters: + - name: body + in: body schema: type: object properties: - errors: + emails: type: array items: type: object properties: - message: + email: type: string - field: - type: string - examples: - application/json: + format: email + example: + emails: + - email: example@example.com + - email: test@example.com + - email: example@test.com + responses: + default: + description: '' + schema: {} + security: + - Authorization: [] + /whitelabel/dns/email: + post: + operationId: POST_whitelabel-dns-email + summary: Email DNS records to a co-worker + tags: + - Email CNAME records + description: |- + **This endpoint is used to share DNS records with a colleagues** + + Use this endpoint to send SendGrid-generated DNS record information to a co-worker so they can enter it into your DNS provider to validate your domain and link branding. + + What type of records are sent will depend on whether you have chosen Automated Security or not. When using Automated Security, SendGrid provides you with three CNAME records. If you turn Automated Security off, you are instead given TXT and MX records. + + If you pass a `link_id` to this endpoint, the generated email will supply the DNS records necessary to complete [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setup. If you pass a `domain_id` to this endpoint, the generated email will supply the DNS records needed to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/). Passing both IDs will generate an email with the records needed to complete both setup steps. + + You can retrieve all your domain IDs from the returned `id` fields for each domain using the "#endpoint:2uc5Dx5bR4iDqCzS9" endpoint. You can retrieve all of your link IDs using the "#endpoint:wQKA6mJBDXXycDkgC" endpoint. + parameters: + - name: body + in: body + schema: + type: object + properties: + link_id: + type: integer + minimum: 0 + desc: The ID of the branded link. + domain_id: + type: integer + minimum: 0 + description: The ID of your SendGrid domain record. + email: + type: string + format: email + description: The email address to send the DNS information to. + message: + type: string + default: Please set these DNS records in our hosting solution. + description: A custom text block to include in the email body sent with the records. + required: + - link_id + - domain_id + - email + example: + link_id: 29719392 + domain_id: 46873408 + email: my_colleague@example.com + message: DNS Record for verification + responses: + '204': + description: '' + '400': + description: '' + schema: + type: object + properties: errors: - - message: resource not found - field: id + type: object + properties: + error: + type: string + field: + type: string security: - Authorization: [] - get: - operationId: GET_v3-senders-sender_id - summary: View a Sender Identity + /ips/pools: + post: + operationId: POST_ips-pools + summary: Create an IP pool tags: - - Sender Identities API + - IP Pools description: |- - **This endpoint allows you to retrieve a specific sender identity.** + **This endpoint allows you to create an IP pool.** - Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`. - produces: - - application/json + Before you can create an IP pool, you need to activate the IP in your SendGrid account: + + 1. Log into your SendGrid account. + 1. Navigate to **Settings** and then select **IP Addresses**. + 1. Find the IP address you want to activate and then click **Edit**. + 1. Check **Allow my account to send mail using this IP address**. + 1. Click **Save**. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name of your new IP pool. + maxLength: 64 + required: + - name + example: + name: marketing responses: '200': description: '' schema: - $ref: '#/definitions/senderID' + $ref: '#/definitions/ip_pool_response' examples: application/json: - id: 1 - nickname: My Sender ID - from: - email: from@example.com - name: Example INC - reply_to: - email: replyto@example.com - name: Example INC - address: 123 Elm St. - address_2: Apt. 456 - city: Denver - state: Colorado - zip: '80202' - country: United States - verified: true - updated_at: 1449872165 - created_at: 1449872165 - locked: false - '404': + name: marketing + security: + - Authorization: [] + get: + operationId: GET_ips-pools + summary: Retrieve all IP pools + tags: + - IP Pools + description: '**This endpoint allows you to get all of your IP pools.**' + responses: + '200': description: '' schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string + type: array + items: + $ref: '#/definitions/ip_pool_response' examples: application/json: - errors: - - message: resource not found - field: id + - name: marketing + - name: transactional security: - Authorization: [] - '/senders/{sender_id}/resend_verification': + '/ips/pools/{pool_name}/ips': parameters: - - name: sender_id + - name: pool_name in: path - description: The ID of the sender identity for which you would like to resend a verification email. + description: 'The name of the IP pool you want to add the address to. If the name contains spaces, they must be URL encoded (e.g., "Test Pool" becomes "Test%20Pool").' required: true - type: integer + type: string post: - operationId: POST_v3-senders-sender_id-resend_verification - summary: Resend Sender Identity Verification + operationId: POST_ips-pools-pool_name-ips + summary: Add an IP address to a pool tags: - - Sender Identities API + - IP Pools description: |- - **This enpdoint allows you to resend a sender identity verification email.** + **This endpoint allows you to add an IP address to an IP pool.** - Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise an email will be sent to the `from.email`. - produces: - - application/json + You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. + + Before you can add an IP to a pool, you need to activate it in your SendGrid account: + + 1. Log into your SendGrid account. + 1. Navigate to **Settings** and then select **IP Addresses**. + 1. Find the IP address you want to activate and then click **Edit**. + 1. Check **Allow my account to send mail using this IP address**. + 1. Click **Save**. + + You can retrieve all of your available IP addresses from the "#endpoint:ebQqc7eNTRxxpCy3G" endpoint. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + type: object + properties: + ip: + type: string + description: The IP address that you want to add to the named pool. + example: + ip: 0.0.0.0 responses: - '204': + '201': description: '' schema: type: object - properties: {} - '400': + properties: + ip: + type: string + description: The IP address. + pools: + type: array + description: The IP pools that this IP address has been added to. + items: + type: string + start_date: + type: integer + description: A Unix timestamp indicating when the warmup process began for the added IP address. + warmup: + type: boolean + description: Indicates if the IP address is in warmup. + required: + - ip + - pools + - start_date + - warmup + examples: + application/json: + ip: 000.00.00.0 + pools: + - test1 + start_date: 1409616000 + warmup: true + '404': description: '' schema: type: object properties: errors: type: array + description: The error returned. items: type: object properties: - message: - type: string field: + type: 'null' + message: type: string + description: A message explaining why the IP address could not be added to the IP Pool. examples: application/json: errors: - - message: The Sender Identity is already verified. No email sent. - field: '' + - field: null + message: resource not found + security: + - Authorization: [] + '/ips/pools/{pool_name}': + parameters: + - name: pool_name + in: path + description: The name of the IP pool that you want to retrieve the IP addresses for. + required: true + type: string + get: + operationId: GET_ips-pools-pool_name + summary: Retrieve all the IPs in a specified pool + tags: + - IP Pools + description: '**This endpoint allows you to get all of the IP addresses that are in a specific IP pool.**' + responses: + '200': + description: '' + schema: + type: object + properties: + pool_name: + type: string + description: The name of the IP pool. + maxLength: 64 + ips: + type: array + description: The IP addresses that belong to this pool. + items: + type: string '404': description: '' schema: @@ -7348,5120 +6651,13524 @@ paths: items: type: object properties: - message: - type: string field: type: string + description: The name of the error. + message: + type: string + description: A message explaining why the IP addresses could not be listed. examples: application/json: errors: - - message: resource not found - field: id + - field: error + message: Unable to locate specified IPs Pool security: - Authorization: [] - /user/settings/enforced_tls: - get: - operationId: GET_user-settings-enforced_tls - summary: Retrieve current Enforced TLS settings. + put: + operationId: PUT_ips-pools-pool_name + summary: Rename an IP pool tags: - - Settings - Enforced TLS - description: |- - **This endpoint allows you to retrieve your current Enforced TLS settings.** - - The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. - - **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. - produces: - - application/json + - IP Pools + description: '**This endpoint allows you to update the name of an IP pool.**' parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The new name for your IP pool. + maxLength: 64 + example: + name: new_pool_name responses: '200': description: '' schema: - type: object - properties: - require_tls: - type: boolean - description: Indicates if the recipient is required to support TLS. - require_valid_cert: - type: boolean - description: Indicates if the recipient is required to have a valid certificate. - required: - - require_tls - - require_valid_cert + $ref: '#/definitions/ip_pool_response' examples: application/json: - require_tls: false - require_valid_cert: false - security: - - Authorization: [] - patch: - operationId: PATCH_user-settings-enforced_tls - summary: Update Enforced TLS settings - tags: - - Settings - Enforced TLS - description: |- - **This endpoint allows you to update your current Enforced TLS settings.** - - The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. - - **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - require_tls: - type: boolean - description: 'Indicates if you want to require your recipients to support TLS. ' - require_valid_cert: - type: boolean - description: Indicates if you want to require your recipients to have a valid certificate. - example: - require_tls: true - require_valid_cert: false - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': + name: new_pool_name + '404': description: '' schema: type: object properties: - require_tls: - type: boolean - description: Indicates if your recipients are required to support TLS. - require_valid_cert: - type: boolean - description: Indicates if your recipients are required to have a valid certificate. - required: - - require_tls - - require_valid_cert + errors: + type: array + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the name of your IP pool could not be updated. examples: application/json: - require_tls: true - require_valid_cert: false + errors: + - field: null + message: ip pool not found security: - Authorization: [] - /user/webhooks/parse/settings: - post: - operationId: POST_user-webhooks-parse-settings - summary: Create a parse setting + delete: + operationId: DELETE_ips-pools-pool_name + summary: Delete an IP pool tags: - - Settings - Inbound Parse - description: |- - **This endpoint allows you to create a new inbound parse setting.** - - The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/parse-setting' - example: - hostname: myhostname.com - url: 'http://email.myhosthame.com' - spam_check: true - send_raw: false - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - IP Pools + description: '**This endpoint allows you to delete an IP pool.**' responses: - '201': + '204': description: '' schema: - $ref: '#/definitions/parse-setting' - examples: - application/json: - url: 'http://email.myhostname.com' - hostname: myhostname.com - spam_check: false - send_raw: true - security: - - Authorization: [] - get: - operationId: GET_user-webhooks-parse-settings - summary: Retrieve all parse settings - tags: - - Settings - Inbound Parse - description: |- - **This endpoint allows you to retrieve all of your current inbound parse settings.** - - The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': + type: object + '404': description: '' schema: type: object properties: - result: - type: array - description: The list of your current inbound parse settings. - items: - $ref: '#/definitions/parse-setting' + error: + type: string + description: An error explaining why the pool could not be deleted. examples: application/json: - result: - - url: 'http://mydomain.com/parse' - hostname: mail.mydomain.com - spam_check: true - send_raw: true + error: Unable to locate specified IPs Pool security: - Authorization: [] - '/user/webhooks/parse/settings/{hostname}': + '/ips/pools/{pool_name}/ips/{ip}': parameters: - - name: hostname + - name: pool_name in: path - description: The hostname associated with the inbound parse setting that you would like to retrieve. + description: The name of the IP pool that you are removing the IP address from. required: true type: string - get: - operationId: GET_user-webhooks-parse-settings-hostname - summary: Retrieve a specific parse setting + - name: ip + in: path + description: The IP address that you wish to remove. + required: true + type: string + delete: + operationId: DELETE_ips-pools-pool_name-ips-ip + summary: Remove an IP address from a pool tags: - - Settings - Inbound Parse - description: |- - **This endpoint allows you to retrieve a specific inbound parse setting.** - - The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - IP Pools + description: '**This endpoint allows you to remove an IP address from an IP pool.**' responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/parse-setting' - examples: - application/json: - url: 'http://mydomain.com/parse' - hostname: mail.mydomain.com - spam_check: true - send_raw: true - security: - - Authorization: [] - patch: - operationId: PATCH_user-webhooks-parse-settings-hostname - summary: Update a parse setting - tags: - - Settings - Inbound Parse - description: |- - **This endpoint allows you to update a specific inbound parse setting.** - - The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/parse-setting' - example: - url: 'http://newdomain.com/parse' - spam_check: false - send_raw: true - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': + type: object + '404': description: '' schema: - $ref: '#/definitions/parse-setting' + type: object + properties: + error: + type: string + description: An error explaining why the IP address could not be removed from the IP pool. examples: application/json: - url: 'http://mydomain.com/parse' - hostname: mail.mydomain.com - spam_check: true - send_raw: true + error: Unable to locate specified IPs Pool security: - Authorization: [] - delete: - operationId: DELETE_user-webhooks-parse-settings-hostname - summary: Delete a parse setting + /ips: + post: + operationId: POST_ips + summary: Add IPs tags: - - Settings - Inbound Parse - description: |- - **This endpoint allows you to delete a specific inbound parse setting.** - - The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the contnet, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). + - IP Addresses + description: '**This endpoint is for adding a(n) IP Address(es) to your account.**' parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' + - name: body + in: body schema: type: object - security: - - Authorization: [] - /mail_settings: - get: - operationId: GET_mail_settings - summary: Retrieve all mail settings - tags: - - Settings - Mail - 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). - produces: - - application/json - parameters: - - name: limit - in: query - description: The number of settings to return. - type: integer - - name: offset - in: query - description: Where in the list of results to begin displaying settings. - type: integer - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + properties: + count: + type: integer + description: The amount of IPs to add to the account. + subusers: + type: array + description: Array of usernames to be assigned a send IP. + items: + type: string + warmup: + type: boolean + default: false + description: Whether or not to warmup the IPs being added. + required: + - count + example: + count: 90323478 + subusers: + - subuser1 + - subuser2 + warmup: true + user_can_send: true responses: - '200': + '201': description: '' schema: type: object properties: - result: + ips: type: array - description: The list of all mail settings. + description: List of IP objects. 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: + ip: type: string - description: The name of the mail setting. - description: - type: string - description: A description of the mail setting. + description: IP added to account. + subusers: + type: array + description: Array of usernames assigned a send IP. + items: + type: string required: - - title - - enabled - - name - - description + - ip + - subusers + remaining_ips: + type: integer + description: The number of IPs that can still be added to the user. + warmup: + type: boolean + description: Whether or not the IPs are being warmed up. required: - - result + - ips + - remaining_ips + - warmup 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. + ips: + - ip: 1.2.3.4 + subusers: + - user + - subuser1 + - ip: 1.2.3.5 + subusers: + - user + - subuser1 + remaining_ips: 1 + warmup: true + '400': + description: '' + schema: + $ref: '#/definitions/error_schema' + examples: + application/json: + errors: + - field: null + message: one or more subusers do not belong to this user security: - Authorization: [] - /mail_settings/bcc: get: - operationId: GET_mail_settings-bcc - summary: Retrieve all BCC mail settings + operationId: GET_ips + summary: Retrieve all IP addresses tags: - - Settings - Mail + - IP Addresses description: |- - **This endpoint allows you to retrieve your current BCC mail settings.** + **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** - 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. + Response includes warm up status, pools, assigned subusers, and reverse DNS info. The start_date field corresponds to when warmup started for that IP. - 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). - produces: - - application/json + A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: ip + in: query + description: The IP address to get + type: string + - name: exclude_whitelabels + in: query + description: Should we exclude reverse DNS records (whitelabels)? + type: boolean + - name: limit + in: query + description: The number of IPs you want returned at the same time. + type: integer + default: 10 + - name: offset + in: query + description: The offset for the number of IPs that you are requesting. + type: integer + default: 0 + - name: subuser + in: query + description: The subuser you are requesting for. + type: string + - name: sort_by_direction + in: query + description: The direction to sort the results. + type: string + enum: + - desc + - asc responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_bcc' + type: array + items: + type: object + properties: + ip: + type: string + description: An IP address. + subusers: + type: array + description: The subusers that are able to send email from this IP. + items: + type: string + rdns: + type: string + description: The reverse DNS record for this IP address. + pools: + type: array + description: The IP pools that this IP has been added to. + items: + type: string + warmup: + type: boolean + description: Indicates if this IP address is currently warming up. + start_date: + type: + - number + - 'null' + description: The date that the IP address was entered into warmup. + whitelabeled: + type: boolean + description: Indicates if this IP address is associated with a reverse DNS record. + assigned_at: + type: + - integer + - 'null' + description: The date that the IP address was assigned to the user. + required: + - ip + - subusers + - pools + - warmup + - start_date + - whitelabeled + - assigned_at examples: application/json: - email: example@example.com - enabled: false + - ip: 192.168.1.1 + pools: + - pool1 + - pool2 + whitelabeled: false + start_date: 1409616000 + subusers: + - tim@sendgrid.net + warmup: false + assigned_at: 1482883200 + - ip: 208.115.214.22 + pools: [] + whitelabeled: true + rdns: o1.email.burgermail.com + start_date: 1409616000 + subusers: [] + warmup: false + assigned_at: 1482883200 security: - Authorization: [] - patch: - operationId: PATCH_mail_settings-bcc - summary: Update BCC mail settings + /ips/remaining: + get: + operationId: GET_ips-remaining + summary: Get remaining IPs count tags: - - Settings - Mail - 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_patch' - example: - enabled: false - email: email@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - IP Addresses + description: '**This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs.**' responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_patch' + type: object + properties: + results: + type: array + items: + type: object + properties: + remaining: + type: integer + description: The number of IPs that can still be added to the user. + period: + type: string + description: The length of time until user can add more IPs. + price_per_ip: + type: number + description: The current cost to add an IP. + required: + - remaining + - period + - price_per_ip + required: + - results examples: application/json: - email: example@example.com - enabled: false + results: + - remaining: 2 + period: month + price_per_ip: 20 security: - Authorization: [] - /mail_settings/address_whitelist: + /ips/assigned: get: - operationId: GET_mail_settings-address_whitelist - summary: Retrieve address whitelist mail settings + operationId: GET_ips-assigned + summary: Retrieve all assigned IPs tags: - - Settings - Mail + - IP Addresses description: |- - **This endpoint allows you to retrieve your current email address whitelist settings.** - - The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + **This endpoint allows you to retrieve only assigned IP addresses.** - 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). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_address_whitelabel' - examples: - application/json: - enabled: false - list: - - example.com - security: - - Authorization: [] - patch: - operationId: PATCH_mail_settings-address_whitelist - summary: Update address whitelist mail settings - tags: - - Settings - Mail + type: array + title: List all assigned IPs response + items: + type: object + properties: + ip: + type: string + description: The IP address. + pools: + type: array + description: The IP pools that this IP address has been added to. + items: + type: string + warmup: + type: boolean + description: Indicates if this IP address is currently warming up. + start_date: + type: integer + description: The start date that this IP address was entered into warmup. + required: + - ip + - pools + - warmup + - start_date + examples: + application/json: + - ip: 167.89.21.3 + pools: + - new_test5 + warmup: true + start_date: 1409616000 + security: + - Authorization: [] + '/ips/{ip_address}': + parameters: + - name: ip_address + in: path + description: The IP address you are retrieving the IP pools for. + required: true + type: string + get: + operationId: GET_ips-ip_address + summary: Retrieve all IP pools an IP address belongs to + tags: + - IP Addresses description: |- - **This endpoint allows you to update your current email address whitelist settings.** + **This endpoint allows you to see which IP pools a particular IP address has been added to.** - 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. + The same IP address can be added to multiple IP pools. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body + A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + responses: + '200': + description: '' schema: type: object properties: - enabled: - type: boolean - description: Indicates if your email address whitelist is enabled. - list: + ip: + type: string + description: The IP address. + subusers: type: array - description: 'Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.' + description: The subusers that can send email using this IP address. items: type: string - example: - enabled: true - list: - - email1@example.com - - example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_address_whitelabel' + rdns: + type: string + description: The reverse DNS record for this IP address. + pools: + type: array + description: The list of IP pools that this IP address belongs to. + items: + type: string + warmup: + type: boolean + description: Indicates if this IP address is currently warming up. + start_date: + type: + - integer + - 'null' + description: The date that the IP address was entered into warmup. + whitelabeled: + type: boolean + description: Indicates if this IP address is associated with a reverse DNS record. + required: + - ip + - subusers + - rdns + - pools + - warmup + - start_date + - whitelabeled examples: application/json: - enabled: true - list: - - email1@example.com + ip: 000.00.00.0 + subusers: + - subuser1 + - subuser2 + rdns: o1.em.example.com + pools: + - test1 + warmup: false + start_date: null + whitelabeled: true security: - Authorization: [] - /mail_settings/footer: + /whitelabel/domains: get: - operationId: GET_mail_settings-footer - summary: Retrieve footer mail settings + operationId: GET_whitelabel-domains + summary: List all authenticated domains tags: - - Settings - Mail - 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). - produces: - - application/json + - Domain Authentication + description: '**This endpoint allows you to retrieve a list of all domains you have authenticated.**' 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 an authenticated domain. + type: string + - name: domain + in: query + description: Search for authenticated domains. + type: string - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_footer' + $ref: '#/definitions/domain-authentication-200-response' examples: application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content + - id: 1 + user_id: 7 + subdomain: mail + domain: example.com + username: jane@example.com + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + legacy: false + automatic_security: true + valid: true + dns: + mail_cname: + valid: true + type: cname + host: mail.example.com + data: u7.wl.sendgrid.net + dkim1: + valid: true + type: cname + host: s1._domainkey.example.com + data: s1._domainkey.u7.wl.sendgrid.net + dkim2: + valid: true + type: cname + host: s2._domainkey.example.com + data: s2._domainkey.u7.wl.sendgrid.net + - id: 2 + user_id: 8 + subdomain: new + domain: example2.com + username: john@example2.com + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_cname: + valid: false + type: mx + host: news.example2.com + data: sendgrid.net + dkim1: + valid: false + type: txt + host: example2.com + data: k=rsa; t=s; p=publicKey + dkim2: + valid: false + type: txt + host: example2.com + data: k=rsa; t=s p=publicKey security: - Authorization: [] - patch: - operationId: PATCH_mail_settings-footer - summary: Update footer mail settings + post: + operationId: POST_whitelabel-domains + summary: Authenticate a domain tags: - - Settings - Mail + - Domain Authentication 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. + **This endpoint allows you to authenticate a domain.** - 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). - consumes: - - application/json - produces: - - application/json + If you are authenticating a domain for a subuser, you have two options: + 1. Use the "username" parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain. + 2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain. parameters: - name: body in: body schema: - $ref: '#/definitions/mail_settings_footer' + type: object + properties: + domain: + type: string + description: Domain being authenticated. + subdomain: + type: string + description: The subdomain to use for this authenticated domain. + username: + type: string + description: The username associated with this domain. + ips: + type: array + description: The IP addresses that will be included in the custom SPF record for this authenticated domain. + 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 authenticated domains set up for manual security. + default: + type: boolean + description: Whether to use this authenticated domain as the fallback if no authenticated domains 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.' + custom_dkim_selector: + type: string + description: Add a custom DKIM selector. Accepts three letters or numbers. + required: + - domain example: - enabled: true - html_content: ... - plain_content: ... + 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 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/mail_settings_footer' + $ref: '#/definitions/authentication::domain' examples: application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content - security: - - Authorization: [] - /mail_settings/forward_spam: - get: - operationId: GET_mail_settings-forward_spam - summary: Retrieve forward spam mail settings + id: 302183 + user_id: 1446226 + subdomain: example + domain: example.com + username: mbernier + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_cname: + valid: false + type: cname + host: example.example.com + data: u1446226.wl.sendgrid.net + dkim1: + valid: false + type: cname + host: s1._domainkey.example.com + data: s1.domainkey.u1446226.wl.sendgrid.net + dkim2: + valid: false + type: cname + host: s2._domainkey.example.com + data: s2.domainkey.u1446226.wl.sendgrid.net + security: + - Authorization: [] + '/whitelabel/domains/{domain_id}': + parameters: + - name: domain_id + in: path + required: true + type: string + get: + operationId: GET_whitelabel-domains-domain_id + summary: Retrieve an authenticated domain tags: - - Settings - Mail - 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). - produces: - - application/json + - Domain Authentication + description: '**This endpoint allows you to retrieve a specific authenticated domain.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' - examples: - application/json: - email: '' - enabled: true + $ref: '#/definitions/authentication::domain' security: - Authorization: [] patch: - operationId: PATCH_mail_settings-forward_spam - summary: Update forward spam mail settings + operationId: PATCH_whitelabel-domains-domain_id + summary: Update an authenticated domain tags: - - Settings - Mail - description: |- - **This endpoint allows you to update 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). - consumes: - - application/json - produces: - - application/json + - Domain Authentication + description: '**This endpoint allows you to update the settings for an authenticated domain.**' parameters: - name: body in: body schema: - $ref: '#/definitions/mail_settings_forward_spam' + type: object + properties: + default: + type: boolean + default: false + description: Indicates whether this is the default authenticated domain. + custom_spf: + type: boolean + default: false + description: Indicates whether to generate a custom SPF record for manual security. example: - email: '' - enabled: false + default: false + custom_spf: true - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' + $ref: '#/definitions/domain-authentication-200-response' examples: application/json: - email: '' - enabled: false + - id: 1 + user_id: 7 + subdomain: mail + domain: example.com + username: jane@example.com + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + legacy: false + automatic_security: true + valid: true + dns: + mail_cname: + valid: true + type: cname + host: mail.example.com + data: u7.wl.sendgrid.net + dkim1: + valid: true + type: cname + host: s1._domainkey.example.com + data: s1._domainkey.u7.wl.sendgrid.net + dkim2: + valid: true + type: cname + host: s2._domainkey.example.com + data: s2._domainkey.u7.wl.sendgrid.net + - id: 2 + user_id: 8 + subdomain: new + domain: example2.com + username: john@example2.com + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_cname: + valid: false + type: mx + host: news.example2.com + data: sendgrid.net + dkim1: + valid: false + type: txt + host: example2.com + data: k=rsa; t=s; p=publicKey + dkim2: + valid: false + type: txt + host: example2.com + data: k=rsa; t=s p=publicKey + security: + - Authorization: [] + delete: + operationId: DELETE_whitelabel-domains-domain_id + summary: Delete an authenticated domain. + tags: + - Domain Authentication + description: '**This endpoint allows you to delete an authenticated domain.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object security: - Authorization: [] - /mail_settings/plain_content: + /whitelabel/domains/default: get: - operationId: GET_mail_settings-plain_content - summary: Retrieve plain content mail settings + operationId: GET_whitelabel-domains-default + summary: Get the default authentication tags: - - Settings - Mail + - Domain Authentication description: |- - **This endpoint allows you to retrieve your current Plain Content mail settings.** + **This endpoint allows you to retrieve the default authentication for a domain.** - 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). - produces: - - application/json + TODO: Check this URL. Does it have a query param, or does the domain go in the URL path? If so, where? parameters: + - name: domain + in: query + description: The domain to find a default authentication. + type: string - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if the Plain Content mail setting is enabled. - examples: - application/json: - enabled: false + $ref: '#/definitions/domain_authentication:domain_spf' security: - Authorization: [] - patch: - operationId: PATCH_mail_settings-plain_content - summary: Update plain content mail settings + '/whitelabel/domains/{id}/ips': + parameters: + - name: id + in: path + description: ID of the domain to which you are adding an IP + required: true + type: integer + post: + operationId: POST_whitelabel-domains-id-ips + summary: Add an IP to an authenticated domain tags: - - Settings - Mail - 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). - consumes: - - application/json - produces: - - application/json + - Domain Authentication + description: '**This endpoint allows you to add an IP address to an authenticated domain.**' 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. + ip: + type: string + description: IP to associate with the domain. Used for manually specifying IPs for custom SPF. + required: + - ip example: - enabled: false + ip: 192.168.0.1 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if your Plain Content mail setting is enabled. + $ref: '#/definitions/domain_authentication:domain_spf' examples: application/json: - enabled: false + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - /mail_settings/spam_check: - get: - operationId: GET_mail_settings-spam_check - summary: Retrieve spam check mail settings + '/whitelabel/domains/{id}/ips/{ip}': + parameters: + - name: id + in: path + required: true + type: string + - name: ip + in: path + required: true + type: string + delete: + operationId: DELETE_whitelabel-domains-id-ips-ip + summary: Remove an IP from an authenticated domain. tags: - - Settings - Mail + - Domain Authentication description: |- - **This endpoint allows you to retrieve your current Spam Checker mail settings.** + **This endpoint allows you to remove an IP address from that domain's authentication.** - 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). - produces: - - application/json + ## URI Parameters + | URI Parameter | Type | Description | + |---|---|---| + | id | integer | ID of the domain to delete the IP from. | + | ip | string | IP to remove from the domain. | parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_spam_check' + $ref: '#/definitions/domain_authentication:domain_spf' examples: application/json: - enabled: false - max_score: 6 - url: 'http://example.com' - security: - - Authorization: [] - patch: - operationId: PATCH_mail_settings-spam_check - summary: Update spam check mail settings - tags: - - Settings - Mail - 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if you want the spam check mail setting to be enabled or not. - url: - type: string - description: The Inbound Parse URL where you would like your spam reports to be sent to. - max_score: - type: integer - default: 5 - description: 'The new max score, or spam threshold that you would like to set for the spam checker.' - minimum: 1 - maximum: 10 - example: - enabled: true - url: url - max_score: 5 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_spam_check' - examples: - application/json: - enabled: false - max_score: 6 - url: 'http://example.com' + id: 1 + domain: example.com + subdomain: mail + username: mail@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - /mail_settings/template: - get: - operationId: GET_mail_settings-template - summary: Retrieve legacy template mail settings + '/whitelabel/domains/{id}/validate': + parameters: + - name: id + in: path + description: ID of the domain to validate. + required: true + type: integer + post: + operationId: POST_whitelabel-domains-id-validate + summary: Validate a domain authentication. tags: - - Settings - Mail - description: |- - **This endpoint allows you to retrieve your current legacy email template settings.** - - This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - produces: - - application/json + - Domain Authentication + description: '**This endpoint allows you to validate an authenticated domain. If it fails, it will return an error message describing why the domain could not be validated.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' - schema: - $ref: '#/definitions/mail_settings_template' - examples: - application/json: - enabled: false - html_content: | -

<% body %>Example

- security: - - Authorization: [] - patch: - operationId: PATCH_mail_settings-template - summary: Update template mail settings - tags: - - Settings - Mail - description: |- - **This endpoint allows you to update your current legacy email template settings.** - - This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body schema: type: object properties: - enabled: + id: + type: integer + description: The ID of the authenticated domain. + valid: type: boolean - description: Indicates if you want to enable the legacy email template mail setting. - html_content: - type: string - description: The new HTML content for your legacy email template. - example: - enabled: true - html_content: <% body %> - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': + description: Indicates if this is a valid authenticated domain. + validation_results: + 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 authenticated domain. + 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 authenticated domain. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + reason: + type: 'null' + dkim2: + type: object + description: A DNS record for this authenticated domain. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + reason: + type: 'null' + spf: + type: object + description: The SPF record for the authenticated domain. + properties: + valid: + type: boolean + description: Indicates if the SPF record is valid. + reason: + type: 'null' + examples: + application/json: + id: 1 + valid: true + validation_resuts: + mail_cname: + valid: false + reason: Expected your MX record to be "mx.sendgrid.net" but found "example.com". + dkim1: + valid: true + reason: null + dkim2: + valid: true + reason: null + spf: + valid: true + reason: null + '500': description: '' schema: type: object properties: - enabled: - type: boolean - description: Indicates if the legacy email template mail setting is enabled. - html_content: - type: string - description: The HTML content of your legacy email template. - required: - - enabled - - html_content + errors: + type: array + items: + type: object + properties: + message: + type: string + description: A message explaining the reason for the error. + required: + - message examples: application/json: - enabled: false - html_content: | -

<% body %>Example

+ errors: + - message: internal error getting TXT security: - Authorization: [] - /mail_settings/bounce_purge: + /whitelabel/domains/subuser: get: - operationId: GET_mail_settings-bounce_purge - summary: Retrieve bounce purge mail settings + operationId: GET_whitelabel-domains-subuser + summary: List the authenticated domain associated with the given user. tags: - - Settings - Mail + - Domain Authentication description: |- - **This endpoint allows you to retrieve your current bounce purge settings.** + **This endpoint allows you to retrieve all of the authenticated domains that have been assigned to a specific subuser.** - 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). - produces: - - application/json + Authenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate a authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The the parent may then associate the authenticated domain via the subuser management tools. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: username + in: query + description: Username for the subuser to find associated authenticated domain. + required: true + type: string responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_bounce_purge' + $ref: '#/definitions/domain_authentication:domain_spf' examples: application/json: - enabled: false - soft_bounces: 1234 - hard_bounces: null + id: 1 + domain: example.com + subdomain: mail + username: mail@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - patch: - operationId: PATCH_mail_settings-bounce_purge - summary: Update bounce purge mail settings + delete: + operationId: DELETE_whitelabel-domains-subuser + summary: Disassociate a authenticated domain from a given user. tags: - - Settings - Mail + - Domain Authentication description: |- - **This endpoint allows you to update your current bounce purge settings.** - - This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + **This endpoint allows you to disassociate a specific authenticated domain from a subuser.** - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - consumes: - - application/json - produces: - - application/json + Authenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate a authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The the parent may then associate the authenticated domain via the subuser management tools. parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_bounce_purge' - example: - enabled: true - hard_bounces: 5 - soft_bounces: 5 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: username + in: query + description: Username for the subuser to find associated authenticated domain. + type: string responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/mail_settings_bounce_purge' - examples: - application/json: - enabled: false - hard_bounces: null - soft_bounces: null + type: object security: - Authorization: [] - /mail_settings/forward_bounce: - get: - operationId: GET_mail_settings-forward_bounce - summary: Retrieve forward bounce mail settings - tags: - - Settings - Mail - 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). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_forward_bounce' - examples: - application/json: - enabled: false - email: null - security: - - Authorization: [] - patch: - operationId: PATCH_mail_settings-forward_bounce - summary: Update forward bounce mail settings + '/whitelabel/domains/{domain_id}/subuser': + parameters: + - name: domain_id + in: path + description: ID of the authenticated domain to associate with the subuser + required: true + type: integer + post: + operationId: POST_whitelabel-domains-domain_id-subuser + summary: Associate a authenticated domain with a given user. tags: - - Settings - Mail + - Domain Authentication description: |- - **This endpoint allows you to update your current bounce forwarding mail settings.** + **This endpoint allows you to associate a specific authenticated domain with a subuser.** - 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). - consumes: - - application/json - produces: - - application/json + Authenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate a authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The the parent may then associate the authenticated domain via the subuser management tools. parameters: - name: body in: body schema: - $ref: '#/definitions/mail_settings_forward_bounce' + type: object + properties: + username: + type: string + description: Username to associate with the authenticated domain. + required: + - username example: - enabled: true - email: example@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + username: jane@example.com responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/mail_settings_forward_bounce' + $ref: '#/definitions/domain_authentication:domain_spf' examples: application/json: - email: '' - enabled: true + id: 1 + domain: example.com + subdomain: mail + username: mail@example.com + user_id: 7 + ips: [] + custom_spf: true + default: false + legacy: false + automatic_security: false + valid: false + dns: + mail_server: + host: mail.example.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: mail.example.com + type: txt + data: 'v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all' + valid: false + domain_spf: + host: example.com + type: txt + data: 'v=spf1 include:mail.example.com -all' + valid: false + dkim: + host: s1._domainkey.example.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - /partner_settings: + /verified_senders/domains: get: - operationId: GET_partner_settings - summary: Returns a list of all partner settings. + operationId: GET_verified_senders-domains + summary: Domain Warn List tags: - - Settings - Partner + - Sender Verification description: |- - **This endpoint allows you to retrieve a list of all partner settings that you can enable.** + **This endpoint returns a list of domains known to implement DMARC and categorizes them by failure type — hard failure or soft failure**. - 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). - 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 + Domains listed as hard failures will not deliver mail when used as a [Sender Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) due to the domain's DMARC policy settings. + + For example, using a `yahoo.com` email address as a Sender Identity will likely result in the rejection of your mail. For more information about DMARC, see [Everything about DMARC](https://sendgrid.com/docs/ui/sending-email/dmarc/). 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: + results: + type: object + required: + - soft_failures + - hard_failures + properties: + soft_failures: + type: array + items: type: string - description: The name of the partner setting. - description: + hard_failures: + type: array + items: type: string - description: A description of this partner setting. - required: - - title - - enabled - - name - - description + required: + - results examples: application/json: - result: - - title: Partner title - enabled: true - name: partner_name - description: A description of a partner. + results: + soft_failures: + - gmail.com + hard_failures: + - yahoo.com + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /partner_settings/new_relic: + /verified_senders/steps_completed: get: - operationId: GET_partner_settings-new_relic - summary: Returns all New Relic partner settings. + operationId: GET_verified_senders-steps_completed + summary: Completed Steps tags: - - Settings - Partner + - Sender Verification description: |- - **This endpoint allows you to retrieve your current New Relic partner settings.** + **This endpoint allows you to determine which of SendGrid’s verification processes have been completed for an account**. - 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). + This endpoint returns boolean values, `true` and `false`, for [Domain Authentication](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#domain-authentication), `domain_verified`, and [Single Sender Verification](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#single-sender-verification), `sender_verified`, for the account. - 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). - produces: - - application/json + An account may have one, both, or neither verification steps completed. If you need to authenticate a domain rather than a Single Sender, see the "#endpoint:aXpkWYramCg4ZNEGT" endpoint. responses: '200': description: '' schema: - $ref: '#/definitions/partner_settings_new_relic' + type: object + properties: + results: + type: object + properties: + sender_verified: + type: boolean + domain_verified: + type: boolean examples: application/json: - enable_subuser_statistics: false - enabled: true - license_key: '' + results: + domain_verified: true + sender_verified: true + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - patch: - operationId: PATCH_partner_settings-new_relic - summary: Updates New Relic partner settings. + /verified_senders: + post: + operationId: POST_verified_senders + summary: Create Verified Sender Request tags: - - Settings - Partner + - Sender Verification description: |- - **This endpoint allows you to update or change your New Relic partner settings.** + **This endpoint allows you to create a new Sender Identify**. - 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). + Upon successful submission of a `POST` request to this endpoint, an identity will be created, and a verification email will be sent to the address assigned to the `from_email` field. You must complete the verification process using the sent email to fully verify the sender. - 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). - consumes: - - application/json - produces: - - application/json + If you need to resend the verification email, you can do so with the Resend Verified Sender Request, `/resend/{id}`, endpoint. + + If you need to authenticate a domain rather than a Single Sender, see the [Domain Authentication API](https://sendgrid.api-docs.io/v3.0/domain-authentication/authenticate-a-domain). parameters: - name: body in: body schema: - type: object - properties: - license_key: - type: string - description: The license key for your New Relic account. - enabled: - type: boolean - description: Indicates if this partner setting is enabled. - enable_subuser_statistics: - type: boolean - description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. - example: - license_key: '' - enabled: true - enable_subuser_statistics: true + $ref: '#/definitions/verified-sender-request-schema' responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/partner_settings_new_relic' + $ref: '#/definitions/verified-sender-response-schema' examples: application/json: - enable_subuser_statistics: true - enabled: true - license_key: '' + id: 1234 + nickname: Example Orders + from_email: orders@example.com + from_name: Example Orders + reply_to: orders@example.com + reply_to_name: Example Orders + address: 1234 Fake St. + address2: PO Box 1234 + state: CA + city: San Francisco + country: USA + zip: '94105' + verified: true + locked: false + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + required: + - message + - error_id + required: + - errors + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /tracking_settings: get: - operationId: GET_tracking_settings - summary: Retrieve Tracking Settings + operationId: GET_verified_senders + summary: Get All Verified Senders tags: - - Settings - Tracking + - Sender Verification description: |- - **This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** + **This endpoint allows you to retrieve all the Sender Identities associated with an 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. + This endpoint will return both verified and unverified senders. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - produces: - - application/json + You can limit the number of results returned using the `limit`, `lastSeenID`, and `id` query string parameters. + + * `limit` allows you to specify an exact number of Sender Identities to return. + * `lastSeenID` will return senders with an ID number occuring after the passed in ID. In other words, the `lastSeenID` provides a starting point from which SendGrid will iterate to find Sender Identities associated with your account. + * `id` will return information about only the Sender Identity passed in the request. parameters: - name: limit in: query - description: The number of settings to return. - type: integer - - name: offset + type: number + - name: lastSeenID + in: query + type: number + - name: id in: query - description: Where in the list of results you want to begin retrieving settings. type: integer - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: type: object properties: - result: + results: 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. + $ref: '#/definitions/verified-sender-response-schema' examples: application/json: - result: - - name: open - title: Open Tracking - description: lorem ipsum... . - enabled: true + results: + - id: 1234 + nickname: Example Orders + from_email: orders@example.com + from_name: Example Orders + reply_to: orders@example.com + reply_to_name: Example Orders + address: 1234 Fake St. + address2: PO Box 1234 + state: CA + city: San Francisco + country: USA + zip: '94105' + verified: true + locked: false + - id: 1235 + nickname: Example Support + from_email: support@example.com + from_name: Example Support + reply_to: support@example.com + reply_to_name: Example Support + address: 1234 Fake St. + address2: PO Box 1234 + state: CA + city: San Francisco + country: USA + zip: '94105' + verified: true + locked: false + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /tracking_settings/click: + '/verified_senders/verify/{token}': + parameters: + - name: token + in: path + required: true + type: string get: - operationId: GET_tracking_settings-click - summary: Retrieve Click Track Settings + operationId: GET_verified_senders-verify-token + summary: Verify Sender Request tags: - - Settings - Tracking + - Sender Verification description: |- - **This endpoint allows you to retrieve your current click tracking setting.** + **This endpoint allows you to verify a sender requests.** - 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). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + The token is generated by SendGrid and included in a verification email delivered to the address that's pending verification. responses: - '200': + '204': + description: '' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': description: '' schema: type: object properties: - enable_text: - type: boolean - description: Indicates if click tracking is enabled for plain text emails. - enabled: - type: boolean - description: Indicates if click tracking is enabled or disabled. + errors: + type: array + items: + type: object + properties: + message: + type: string + error_id: + type: string + required: + - message + - error_id required: - - enable_text - - enabled - examples: - application/json: - enable_text: false - enabled: true + - errors + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] + '/verified_senders/{id}': + parameters: + - name: id + in: path + required: true + type: string patch: - operationId: PATCH_tracking_settings-click - summary: Update Click Tracking Settings + operationId: PATCH_verified_senders-id + summary: Edit Verified Sender tags: - - Settings - Tracking + - Sender Verification description: |- - **This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** + **This endpoint allows you to update an existing Sender Identity**. - 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. + Pass the `id` assigned to a Sender Identity to this endpoint as a path parameter. Include any fields you wish to update in the request body in JSON format. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - consumes: - - application/json - produces: - - application/json + You can retrieve the IDs associated with Sender Identities by passing a `GET` request to the Get All Verified Senders endpoint, `/verified_senders`. + + **Note:** Unlike a `PUT` request, `PATCH` allows you to update only the fields you wish to edit. Fields that are not passed as part of a request will remain unaltered. parameters: - name: body in: body schema: - type: object - properties: - enabled: - type: boolean - description: The setting you want to use for click tracking. - example: - enabled: true - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + $ref: '#/definitions/verified-sender-request-schema' responses: '200': + description: '' + schema: + $ref: '#/definitions/verified-sender-response-schema' + examples: + application/json: + id: 1234 + nickname: Example Orders + from_email: orders@example.com + from_name: Example Orders + reply_to: orders@example.com + reply_to_name: Example Orders + address: 1234 Fake St. + address2: PO Box 1234 + state: CA + city: San Francisco + country: USA + zip: '94105' + verified: true + locked: false + '400': description: '' schema: type: object properties: - enable_text: - type: boolean - description: Indicates if click tracking is enabled for plain text emails - enabled: - type: boolean - description: The new setting new setting for click tracking. + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + required: + - message + - error_id required: - - enable_text - - enabled - examples: - application/json: - enable_text: false - enabled: true + - errors + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + error_id: + type: string + required: + - message + - error_id + required: + - errors + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + error_id: + type: string + required: + - message + - error_id + required: + - errors + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /tracking_settings/google_analytics: - get: - operationId: GET_tracking_settings-google_analytics - summary: Retrieve Google Analytics Settings + delete: + operationId: DELETE_verified_senders-id + summary: Delete Verified Sender tags: - - Settings - Tracking + - Sender Verification description: |- - **This endpoint allows you to retrieve your current setting for Google Analytics.** - - For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). - - We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + **This endpoint allows you to delete a Sender Identity**. - 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. + Pass the `id` assigned to a Sender Identity to this endpoint to delete the Sender Identity from your account. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + You can retrieve the IDs associated with Sender Identities using the #endpoint:ow3obGPTZxwZAJtkn endpoint. responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/google_analytics_settings' - examples: - application/json: - enabled: true - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' - security: - - Authorization: [] - patch: - operationId: PATCH_tracking_settings-google_analytics - summary: Update Google Analytics Settings - tags: - - Settings - Tracking - 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body + type: object + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + description: '' schema: - $ref: '#/definitions/google_analytics_settings' - example: - enabled: true - utm_source: sendgrid.com - utm_medium: email - utm_term: '' - utm_content: '' - utm_campaign: website - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + error_id: + type: string + required: + - message + - error_id + '404': description: '' schema: - $ref: '#/definitions/google_analytics_settings' - examples: - application/json: - enabled: true - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + error_id: + type: string + required: + - message + - error_id + required: + - errors + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /tracking_settings/open: - get: - operationId: GET_tracking_settings-open - summary: Get Open Tracking Settings + '/verified_senders/resend/{id}': + parameters: + - name: id + in: path + required: true + type: string + post: + operationId: POST_verified_senders-resend-id + summary: Resend Verified Sender Request tags: - - Settings - Tracking + - Sender Verification 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. + **This endpoint allows you to resend a verification email to a specified Sender Identity**. - 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. + Passing the `id` assigned to a Sender Identity to this endpoint will resend a verification email to the `from_address` associated with the Sender Identity. This can be useful if someone loses their verification email or needs to have it resent for any other reason. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + You can retrieve the IDs associated with Sender Identities by passing a "#endpoint:ow3obGPTZxwZAJtkn" endpoint. responses: - '200': + '204': + description: '' + schema: + type: object + '400': description: '' schema: type: object properties: - enabled: - type: boolean - description: Indicates if open tracking is enabled. + errors: + type: array + items: + type: object + properties: + message: + type: string + error_id: + type: string + required: + - message + - error_id required: - - enabled - examples: - application/json: - enabled: true + - errors + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + error_id: + type: string + required: + - message + - error_id + required: + - errors + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - patch: - operationId: PATCH_tracking_settings-open - summary: Update Open Tracking Settings + /designs: + post: + operationId: POST-design + summary: Create Design tags: - - Settings - Tracking + - Designs API description: |- - **This endpoint allows you to update your current settings for open tracking.** + **This endpoint allows you to create a new design**. - 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 add a new design by passing data, including a string of HTML email content, to `/designs`. When creating designs from scratch, be aware of the styling constraints inherent to many email clients. For a list of best practices, see our guide to [Cross-Platform Email Design](https://sendgrid.com/docs/ui/sending-email/cross-platform-html-design/). - 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 Design Library can also convert your design’s HTML elements into drag and drop modules that are editable in the Designs Library user interface. For more, visit the [Design and Code Editor documentation](https://sendgrid.com/docs/ui/sending-email/editor/#drag--drop-markup). - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - consumes: - - application/json - produces: - - application/json + Because the `/designs` endpoint makes it easy to add designs, you can create a design with your preferred tooling or migrate designs you already own without relying on the Design Library UI. parameters: - name: body in: body schema: - type: object - properties: - enabled: - type: boolean - description: The new status that you want to set for open tracking. + $ref: '#/definitions/design-input' example: - enabled: true - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + name: 'Ahoy, World!' + editor: design + subject: Getting Started + html_content: |- + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + + + +
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + plain_content: |- + Ahoy, World! + + {{Sender_Name}} + + {{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}} + + Unsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} ) responses: - '200': + '201': description: '' schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if open tracking is enabled. - required: - - enabled - examples: - application/json: - enabled: true + $ref: '#/definitions/design-output' + examples: + application/json: + id: 3247eaea-c912-42a3-b0bc-60bdaf210396 + name: 'Ahoy, World!' + html_content: |- + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + + + +
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + plain_content: |- + Ahoy, World! + + {{Sender_Name}} + + {{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}} + + Unsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} ) + generate_plain_content: false + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/kjlrmded0qnrscv8zqr39npoimrpdwgiax59q8iq6ovj7yoks2fzxoxpfjpwph6o.png + subject: Getting Started + created_at: '2021-04-30T18:51:20Z' + updated_at: '2021-04-30T18:51:20Z' + editor: design + categories: [] + '400': + description: '' + schema: + $ref: '#/definitions/api-errors' security: - Authorization: [] - /tracking_settings/subscription: get: - operationId: GET_tracking_settings-subscription - summary: Retrieve Subscription Tracking Settings + operationId: LIST-designs + summary: List Designs tags: - - Settings - Tracking + - Designs API 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. + **This endpoint allows you to retrieve a list of designs already stored in your Design Library**. - 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. + A GET request to `/designs` will return a list of your existing designs. This endpoint will not return the pre-built Twilio SendGrid designs. Pre-built designs can be retrieved using the `/designs/pre-builts` endpoint, which is detailed below. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - produces: - - application/json + By default, you will receive 100 results per request; however, you can modify the number of results returned by passing an integer to the `page_size` query parameter. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:designsQueryStrings:page_size' + - $ref: '#/parameters/trait:designsQueryStrings:page_token' + - $ref: '#/parameters/trait:designsQueryStrings:summary' responses: '200': description: '' schema: - $ref: '#/definitions/subscription_tracking_settings' + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/design-output-summary' + _metadata: + $ref: '#/definitions/_metadata' examples: application/json: - enabled: true - html_content: | -

Something something unsubscribe <% %> something something

- landing: | -

subscribehere

- plain_content: Something something unsubscribe <% %> something something - replace: thetag - url: '' + result: + - id: 3247eaea-c912-42a3-b0bc-60bdaf210396 + name: Welcome Email + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/llny8o5b3m636z92p7hbjnmq1jvpka39p370jwtin2s1wxv7x1sgm0y5fk518d0s.png + subject: Welcom to the Cake or Pie Cafe + created_at: '2021-04-09T17:29:46Z' + updated_at: '2021-04-09T17:29:55Z' + editor: code + categories: + - welcome + - new customer + - id: 02dfd792-f31f-439a-a79e-5c47fbcfdbac + name: Monthly Promo + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/hfyxahd7ues2ajuoeoqq2xe6ibdasl1q89ox0y9ncya2ftpoicssmtf9ddus4c39.png + subject: Free Dozen Cupcakes + created_at: '2021-04-09T17:29:21Z' + updated_at: '2021-04-09T17:29:42Z' + editor: design + categories: + - promo + - coupon + - id: e54be823-19ef-4c6f-8b60-efd7514f492d + name: 'Duplicate: Ingrid & Anders' + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/12kni9gjpyb9uxmwr9vk7unycjr70u95zoyhe9sg2zounul2zg7dih1s20k13q2z.png + subject: Welcome to Ingrid & Anders! + created_at: '2020-10-09T17:33:46Z' + updated_at: '2021-04-07T19:57:52Z' + editor: design + categories: [] + _metadata: + self: 'https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I' + count: 3 security: - Authorization: [] - patch: - operationId: PATCH_tracking_settings-subscription - summary: Update Subscription Tracking Settings + '/designs/{id}': + parameters: + - name: id + in: path + description: The ID of the Design you want to duplicate. + required: true + type: string + format: uuid + post: + operationId: POST-design + summary: Duplicate Design tags: - - Settings - Tracking + - Designs API description: |- - **This endpoint allows you to update your current settings for subscription tracking.** + **This endpoint allows you to duplicate one of your existing designs**. - Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + Modifying an existing design is often the easiest way to create something new. - 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. + You are not required to pass any data in the body of a request to this endpoint. If you choose to leave the `name` field blank, your duplicate will be assigned the name of the design it was copied from with the text "Duplicate: " prepended to it. This name change is only a convenience, as the duplicate will be assigned a unique ID that differentiates it from your other designs. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - consumes: - - application/json - produces: - - application/json + You can modify your duplicate’s name at the time of creation by passing an updated value to the `name` field when making the initial request. + More on retrieving design IDs can be found below. parameters: - name: body in: body schema: - $ref: '#/definitions/subscription_tracking_settings' + $ref: '#/definitions/design-duplicate-input' example: - enabled: true - landing: landing page html - url: url - replace: replacement tag - html_content: html content - plain_content: text content - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + name: 'Ahoy, Cake or Pie Cafe!' + editor: design responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/subscription_tracking_settings' - examples: - application/json: - enabled: true - landing: landing page html - url: url - replace: replacement tag - html_content: html content - plain_content: text content + $ref: '#/definitions/design-output' + examples: + application/json: + id: 15b85720-ce48-48ef-8a07-672b0d3455da + name: 'Ahoy, Cake or Pie Cafe!' + html_content: |- + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + + + +
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + plain_content: |- + Ahoy, World! + + {{Sender_Name}} + + {{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}} + + Unsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} ) + generate_plain_content: false + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/79bb769ae6464960a307040120ad6f9921896fe9825e845ad1f24d12285ea068.png + subject: Getting Started + created_at: '2021-04-30T19:00:16Z' + updated_at: '2021-04-30T19:00:16Z' + editor: design + categories: [] + '400': + description: '' + schema: + $ref: '#/definitions/api-error' + '404': + description: '' + schema: + $ref: '#/definitions/api-errors' security: - Authorization: [] - /suppression/spam_reports: get: - operationId: GET_suppression-spam_reports - summary: Retrieve all spam reports + operationId: GET-design + summary: Get Design tags: - - Spam Reports API + - Designs API description: |- - **This endpoint allows you to retrieve all spam reports.** + **This endpoint allows you to retrieve a single design**. - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + A GET request to `/designs/{id}` will retrieve details about a specific design in your Design Library. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - produces: - - application/json - parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when a spam report was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when a spam report was created (inclusive). - type: integer - - name: limit - in: query - description: Limit the number of results to be displayed per page. - type: integer - - name: offset - in: query - description: Paging offset. The point in the list to begin displaying results. - type: integer - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + This endpoint is valuable when retrieving information stored in a field that you wish to update using a PATCH request. responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the spam report was made. - email: - type: string - description: The email address of the recipient who marked your message as spam. - ip: - type: string - description: The IP address that the message was sent on. - required: - - created - - email - - ip - examples: - application/json: - - created: 1443651141 - email: user1@example.com - ip: 10.63.202.100 - - created: 1443651154 - email: user2@example.com - ip: 10.63.202.100 + $ref: '#/definitions/design-output' + examples: + application/json: + id: 15b85720-ce48-48ef-8a07-672b0d3455da + name: 'Ahoy, World!' + html_content: |- + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + + + +
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + plain_content: |- + Ahoy, World! + + {{Sender_Name}} + + {{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}} + + Unsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} ) + generate_plain_content: false + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/5yysvuyi1lpdnxo1ym8ax8yd7ompve3azjtme76gamdace01vko3eyn1kzso1lhy.png + subject: Getting Started + created_at: '2021-04-30T18:51:20Z' + updated_at: '2021-04-30T18:51:20Z' + editor: design + categories: [] + '400': + description: '' + schema: + $ref: '#/definitions/api-errors' + '404': + description: '' + schema: + $ref: '#/definitions/api-errors' security: - Authorization: [] - delete: - operationId: DELETE_suppression-spam_reports - summary: Delete spam reports + patch: + operationId: PUT-design + summary: Update Design tags: - - Spam Reports API + - Designs API description: |- - **This endpoint allows you to delete your spam reports.** - - There are two options for deleting spam reports: + **This endpoint allows you to edit a design**. - 1) You can delete all spam reports by setting "delete_all" to true in the request body. - 2) You can delete some spam reports by specifying the email addresses in an array in the request body. + The Design API supports PATCH requests, which allow you to make partial updates to a single design. Passing data to a specific field will update only the data stored in that field; all other fields will be unaltered. - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + For example, updating a design's name requires that you make a PATCH request to this endpoint with data specified for the `name` field only. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - produces: - - application/json + ``` + { + "name": "" + } + ``` parameters: - name: body in: body schema: type: object properties: - delete_all: + name: + type: string + description: Name of the Design. + maxLength: 100 + default: My Design + html_content: + type: string + description: The HTML content of the Design. + maxLength: 1048576 + plain_content: + type: string + description: Plain text content of the Design. + maxLength: 1048576 + default: + generate_plain_content: type: boolean - description: Indicates if you want to delete all email addresses on the spam report list. - emails: + description: 'If true, plain_content is always generated from html_content. If false, plain_content is not altered.' + default: true + subject: + type: string + description: Subject of the Design. + maxLength: 5000 + categories: type: array - description: A list of specific email addresses that you want to remove from the spam report list. + description: The list of categories applied to the design + uniqueItems: true + maxItems: 10 items: type: string + maxLength: 255 example: - delete_all: false - emails: - - example1@example.com - - example2@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + name: 'Ahoy, World!' + subject: Getting Started + html_content: |- + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + + + +
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + generate_plain_content: false + categories: + - promotions + responses: + '200': + description: '' + schema: + $ref: '#/definitions/design-output' + examples: + application/json: + id: 15b85720-ce48-48ef-8a07-672b0d3455da + name: 'Ahoy, World!' + html_content: |- + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + + + +
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + generate_plain_content: false + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/5yysvuyi1lpdnxo1ym8ax8yd7ompve3azjtme76gamdace01vko3eyn1kzso1lhy.png + subject: Getting Started + created_at: '2021-04-30T18:51:20Z' + updated_at: '2021-04-30T18:51:20Z' + editor: design + categories: + - promotions + '400': + description: '' + schema: + $ref: '#/definitions/api-errors' + '404': + description: '' + schema: + $ref: '#/definitions/api-errors' + security: + - Authorization: [] + delete: + operationId: DELETE-design + summary: Delete Design + tags: + - Designs API + description: |- + **This endpoint allows you to delete a single design**. + + Be sure to check the ID of the design you intend to delete before making this request; deleting a design is a permanent action. responses: '204': description: '' schema: type: object - properties: {} + '400': + description: '' + schema: + $ref: '#/definitions/api-errors' + '404': + description: '' + schema: + $ref: '#/definitions/api-errors' security: - Authorization: [] - '/suppression/spam_reports/{email}': + '/designs/pre-builts/{id}': parameters: - - name: email + - name: id in: path - description: The email address of a specific spam report that you want to retrieve. + description: The ID of the pre-built Design you want to duplicate. required: true type: string - get: - operationId: GET_suppression-spam_reports-email - summary: Retrieve a specific spam report + format: uuid + post: + operationId: POST-sendgrid-pre-built-design + summary: Duplicate SendGrid Pre-built Design tags: - - Spam Reports API + - Designs API description: |- - **This endpoint allows you to retrieve a specific spam report.** + **This endpoint allows you to duplicate one of the pre-built Twilio SendGrid designs**. - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + Like duplicating one of your existing designs, you are not required to pass any data in the body of a request to this endpoint. If you choose to leave the `name` field blank, your duplicate will be assigned the name of the design it was copied from with the text "Duplicate: " prepended to it. This name change is only a convenience, as the duplicate design will be assigned a unique ID that differentiates it from your other designs. You can retrieve the IDs for Twilio SendGrid pre-built designs using the #endpoint:onypXY6DEQabeqdF7 endpoint. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - produces: - - application/json + You can modify your duplicate’s name at the time of creation by passing an updated value to the `name` field when making the initial request. + More on retrieving design IDs can be found above. parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + $ref: '#/definitions/design-duplicate-input' + example: + name: 'Ahoy, Cake or Pie Cafe!' + editor: design responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp that indicates when the recipient marked your message as spam. - email: - type: string - description: The email address of the recipient that marked your message as spam. - ip: - type: string - description: The IP address that the message was sent from. - required: - - created - - email - - ip + $ref: '#/definitions/design-output' + examples: + application/json: + id: abe0877f-a224-21e2-b62e-c789d326cda5 + name: 'Ahoy, Pre-built Design!' + html_content: |- + + + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + +
Off Grid Adventures
+ + + +
+ + + +
Welcome to the family!
+ + + +
You've found a community of travelers that are just like you.
+
 
+
We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.
+
 
+
Ready for your next authentic travel experience?
Browse Gallery
+ + + +
+ + + +
+
+ + + +
+ + + + +
+
+ + + +
+
+ + + + + +
+ + +
+

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + plain_content: |- + You've found the secret! + + Welcome to the family! + + You've found a community of travelers that are just like you. + + We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination. + + Ready for your next authentic travel experience? + + Browse Gallery + + ( https://www.facebook.com/sendgrid/ ) ( https://twitter.com/sendgrid?ref_src=twsrc%5egoogle%7ctwcamp%5eserp%7ctwgr%5eauthor ) ( https://www.instagram.com/sendgrid/?hl=en ) ( https://www.pinterest.com/sendgrid/ ) + + {{Sender_Name}} + + {{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}} + + Unsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} ) + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png + subject: Welcome to the family! + created_at: '2021-04-30T19:15:28Z' + updated_at: '2021-04-30T19:15:28Z' + editor: design + categories: [] + '400': + description: '' + schema: + $ref: '#/definitions/api-errors' + '404': + description: '' + schema: + $ref: '#/definitions/api-errors' + security: + - Authorization: [] + get: + operationId: GET-sendgrid-pre-built-design + summary: Get SendGrid Pre-built Design + tags: + - Designs API + description: |- + **This endpoint allows you to retrieve a single pre-built design**. + + A GET request to `/designs/pre-builts/{id}` will retrieve details about a specific pre-built design. + + This endpoint is valuable when retrieving details about a pre-built design that you wish to duplicate and modify. + responses: + '200': + description: '' + schema: + $ref: '#/definitions/design-output' + examples: + application/json: + id: 6ad69134-7165-48cb-964a-6c3cf03e8af8 + name: Off Grid Adventures + html_content: |- + + + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + +
Off Grid Adventures
+ + + +
+ + + +
Welcome to the family!
+ + + +
You've found a community of travelers that are just like you.
+
 
+
We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination.
+
 
+
Ready for your next authentic travel experience?
Browse Gallery
+ + + +
+ + + +
+
+ + + +
+ + + + +
+
+ + + +
+
+ + + + + +
+ + +
+

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + plain_content: |- + You've found the secret! + + Welcome to the family! + + You've found a community of travelers that are just like you. + + We don't want to be stuck in tourist traps that isolate us from vibrant, local experiences. We want to discover the hidden gems and less-traveled roads of our next destination. + + Ready for your next authentic travel experience? + + Browse Gallery + + ( https://www.facebook.com/sendgrid/ ) ( https://twitter.com/sendgrid?ref_src=twsrc%5egoogle%7ctwcamp%5eserp%7ctwgr%5eauthor ) ( https://www.instagram.com/sendgrid/?hl=en ) ( https://www.pinterest.com/sendgrid/ ) + + {{Sender_Name}} + + {{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}} + + Unsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} ) + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png + subject: Welcome to the family! + created_at: '2019-09-10T02:11:34Z' + updated_at: '2021-01-11T21:47:52Z' + editor: design + categories: [] + '400': + description: '' + schema: + $ref: '#/definitions/api-errors' + '404': + description: '' + schema: + $ref: '#/definitions/api-errors' + security: + - Authorization: [] + /designs/pre-builts: + get: + operationId: LIST-Sendgrid-Pre-built-designs + summary: List SendGrid Pre-built Designs + tags: + - Designs API + description: |- + **This endpoint allows you to retrieve a list of pre-built designs provided by Twilio SendGrid**. + + Unlike the `/designs` endpoint where *your* designs are stored, a GET request made to `designs/pre-builts` will retrieve a list of the pre-built Twilio SendGrid designs. This endpoint will not return the designs stored in your Design Library. + + By default, you will receive 100 results per request; however, you can modify the number of results returned by passing an integer to the `page_size` query parameter. + + This endpoint is useful for retrieving the IDs of Twilio SendGrid designs that you want to duplicate and modify. + parameters: + - $ref: '#/parameters/trait:designsQueryStrings:page_size' + - $ref: '#/parameters/trait:designsQueryStrings:page_token' + - $ref: '#/parameters/trait:designsQueryStrings:summary' + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/design-output-summary' + _metadata: + $ref: '#/definitions/_metadata' examples: application/json: - - created: 1454433146 - email: test1@example.com - ip: 10.89.32.5 + result: + - id: 6ad69134-7165-48cb-964a-6c3cf03e8af8 + name: Off Grid Adventures + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/a85b4b202ff28094828f11ff472360caecf67ead2d186b69b45c904b9251aa0b.png + subject: Welcome to the family! + created_at: '2019-09-10T02:11:34Z' + updated_at: '2021-01-11T21:47:52Z' + editor: design + categories: [] + - id: b0a9c6f7-a9a1-4b52-b0c5-16fc6f4cdb2b + name: Song Riddle + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/4ef3a39249f3accb8461b03950c071454a745a232508feca89a626b3e7f578d3.png + subject: Welcome to Song Riddle! + created_at: '2019-09-10T02:12:32Z' + updated_at: '2021-01-11T21:46:43Z' + editor: design + categories: [] + - id: f8d8da76-bcca-4cfe-b809-733887855f57 + name: Ingrid & Anders 1 + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/15c97ffa97ee31693581a67526728d096eef00adfbaa34bb030d91034d477da4.png + subject: Welcome to Ingrid & Anders! + created_at: '2019-09-10T02:10:38Z' + updated_at: '2021-01-11T21:45:05Z' + editor: design + categories: [] + - id: 2935a7d0-7f02-4e0f-a570-dc302ce09749 + name: Ingrid & Anders 2 + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/7b36a6c0955cab0c350d105114ad248700a685bd11032592cdef85ae26540afc.png + subject: Check out these exclusive deals! + created_at: '2019-09-10T02:09:31Z' + updated_at: '2021-01-11T21:44:08Z' + editor: design + categories: [] + - id: 7826ef14-7ba6-4dbc-91f0-a8c610ebe962 + name: Ingrid & Anders 3 + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/6dd8dd73a1a62bd7a76c4313b52d7c749250d49e31b19cce718906655fcbc675.png + subject: Join our VIP club and save big! + created_at: '2019-09-10T02:08:29Z' + updated_at: '2021-01-11T21:41:35Z' + editor: design + categories: [] + - id: 41da47e7-d3e2-491b-a83f-f499a4139d6a + name: Mercado + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/9cc87cc7671719712d9d363184995d0ec05103355db300ff03641fe9e205651d.png + subject: Subject + created_at: '2019-09-10T02:03:06Z' + updated_at: '2021-01-11T21:39:23Z' + editor: design + categories: [] + _metadata: + self: 'https://api.sendgrid.com/v3/designs/pre-builts?page_token=yYzyCxj-iIVgP54t6NjKkunDCKYLLpngo-5vAsfYXz0To34U' + count: 6 security: - Authorization: [] - delete: - operationId: DELETE_suppression-spam_reports-email - summary: Delete a specific spam report + /marketing/contacts: + put: + operationId: PUT_mc-contacts + summary: Add or Update a Contact tags: - - Spam Reports API + - Contacts description: |- - **This endpoint allows you to delete a specific spam report.** + **This endpoint allows the [upsert](https://en.wiktionary.org/wiki/upsert) (insert or update) of up to 30,000 contacts, or 6MB of data, whichever is lower**. + + Because the creation and update of contacts is an asynchronous process, the response will not contain immediate feedback on the processing of your upserted contacts. Rather, it will contain an HTTP 202 response indicating the contacts are queued for processing or an HTTP 4XX error containing validation errors. Should you wish to confirm your contacts have been updated or added, you can use the #endpoint:oNz2fgJriXmSkdyEe endpoint. + + Please note that custom fields need to have been already created if you wish to set their values for the contacts being upserted. To do this, please use the #endpoint:oC6DjiarRqXQu5kTm endpoint. + + You will see a `job_id` in the response to your request. This can be used to check the status of your upsert job. To do so, please use the #endpoint:m5WnoiseMvTXuNwZt endpoint. - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + The email field is case sensitive. If you add an email with capital letters then try to use the #endpoint:oNz2fgJriXmSkdyEe endpoint, you will need to apply the same case you used when updating or adding the contact. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + If the contact already exists in the system, any entries you submit via this endpoint will update the existing contact. parameters: - name: body in: body schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + type: object + properties: + list_ids: + type: array + description: An array of List ID strings that this contact will be added to. + items: + type: string + format: uuid + contacts: + type: array + description: 'One or more contacts objects that you intend to upsert. The available fields for a contact, including the required `email` field are described below.' + minItems: 1 + maxItems: 30000 + items: + $ref: '#/definitions/contact-request' + required: + - contacts responses: - '204': + '202': description: '' schema: type: object - properties: {} + properties: + job_id: + type: string + description: 'Indicates that the contacts are queued for processing. Check the job status with the #endpoint:m5WnoiseMvTXuNwZt endpoint.' + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + $ref: '#/definitions/error' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /stats: - get: - operationId: GET_stats - summary: Retrieve global email statistics + delete: + operationId: DELETE_mc-contacts + summary: Delete Contacts tags: - - Stats + - Contacts description: |- - **This endpoint allows you to retrieve all of your global email statistics between a given date range.** + **This endpoint can be used to delete one or more contacts**. - Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. - produces: - - application/json + The query parameter `ids` must set to a comma-separated list of contact IDs for bulk contact deletion. + + The query parameter `delete_all_contacts` must be set to `"true"` to delete **all** contacts. + + You must set either `ids` or `delete_all_contacts`. + + Deletion jobs are processed asynchronously. 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 + - name: delete_all_contacts in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' + description: Must be set to `"true"` to delete all contacts. 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 + - name: ids in: query - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + description: A comma-separated list of contact IDs. required: false type: string - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '202': + description: '' + schema: + type: object + description: The deletion job has been accepted and is being processed. + properties: + job_id: + type: object + description: The deletion job ID. + required: + - job_id + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + required: + - errors + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + get: + operationId: GET_mc-contats + summary: Get Sample Contacts + tags: + - Contacts + description: |- + **This endpoint will return up to 50 of the most recent contacts uploaded or attached to a list**. + + This list will then be sorted by email address. + + The full contact count is also returned. + + Please note that pagination of the contacts has been deprecated. 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: + result: + type: array + items: + $ref: '#/definitions/contact-details3' + _metadata: + $ref: '#/definitions/selfmetadata' + contact_count: + type: integer + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + $ref: '#/definitions/error' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + type: object + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + /marketing/contacts/count: + get: + operationId: GET_mc-contacts-count + summary: Get Total Contact Count + tags: + - Contacts + description: '**This endpoint returns the total number of contacts you have stored.**' + responses: + '200': + description: '' + schema: + type: object + properties: + contact_count: + type: integer + description: The total number of contacts. + billable_count: + type: integer + default: 0 + description: The count of contacts this month for billing purposes. + minimum: 0 + billable_breakdown: + type: object + description: '`billable_breakdown` will only appear to the parent user in an account with subusers.' + properties: + total: + type: integer + description: The sum of all the subuser's billable contacts + breakdown: 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 + description: A map of each subuser's billable contact usage. Each key is the subuser's ID and each value is the usage thus far this month. + minProperties: 0 + required: + - contact_count + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /geo/stats: - get: - operationId: GET_geo-stats - summary: Retrieve email statistics by country and state/province. + /marketing/contacts/exports: + post: + operationId: POST_mc-contacts-exports + summary: Export Contacts tags: - - Stats + - Contacts description: |- - **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** + **Use this endpoint to export lists or segments of contacts**. - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + If you would just like to have a link to the exported list sent to your email set the `notifications.email` option to `true` in the `POST` payload. - 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). - produces: - - application/json + If you would like to download the list, take the `id` that is returned and use the #endpoint:TrwE7WeCWP8hEbYis endpoint to get the `urls`. Once you have the list of URLs, make a `GET` request to each URL provided to download your CSV file(s). + + You specify the segements and or/contact lists you wish to export by providing the relevant IDs in, respectively, the `segment_ids` and `list_ids` fields in the request body. + + The lists will be provided in either JSON or CSV files. To specify which of these you would required, set the request body `file_type` field to `json` or `csv`. + + You can also specify a maximum file size (in MB). If the export file is larger than this, it will be split into multiple files. 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 - default: The date the request is made. - - name: country - in: query - description: The country you would like to see statistics for. Currently only supported for US and CA. - required: false - type: string - enum: - - US - - CA - - $ref: '#/parameters/trait:authorizationHeader:Authorization' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: body + in: body + schema: + type: object + properties: + list_ids: + description: IDs of the contact lists you want to export. + type: array + items: + type: string + format: uuid + segment_ids: + description: IDs of the contact segments you want to export. + type: array + items: + type: string + notifications: + type: object + properties: + email: + type: boolean + file_type: + type: string + enum: + - csv + - json + description: File type for export file. Choose from `json` or `csv`. + default: csv + max_file_size: + description: 'The maximum size of an export file in MB. Note that when this option is specified, multiple output files may be returned from the export.' + default: 5000 + type: integer + responses: + '202': + description: '' + schema: + type: object + properties: + _metadata: + $ref: '#/definitions/metadata' + id: + type: string + description: The ID of the export job. + required: + - _metadata + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + $ref: '#/definitions/error' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + get: + operationId: GET_marketing-contacts-exports + summary: Get All Existing Exports + tags: + - Contacts + description: |- + **Use this endpoint to retrieve details of all current exported jobs**. + + It will return an array of objects, each of which records an export job in flight or recently completed. + + Each object's `export_type` field will tell you which kind of export it is and its `status` field will indicate what stage of processing it has reached. Exports which are `ready` will be accompanied by a `urls` field which lists the URLs of the export's downloadable files — there will be more than one if you specified a maximum file size in your initial export request. + + Use this endpoint if you have exports in flight but do not know their IDs, which are required for #endpoint:TrwE7WeCWP8hEbYis. 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 - /devices/stats: - get: - operationId: GET_devices-stats - summary: Retrieve email statistics by device type. - tags: - - Stats - 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)." - 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 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - /clients/stats: - get: - operationId: GET_clients-stats - summary: Retrieve email statistics by client type. - tags: - - Stats - 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). - 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 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - 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: - operationId: GET_clients-client_type-stats - summary: Retrieve stats by a specific client type. - tags: - - Stats - description: |- - **This endpoint allows you to retrieve your email statistics segmented by a specific 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. - - ## 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). - 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 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - /mailbox_providers/stats: - get: - operationId: GET_mailbox_providers-stats - summary: Retrieve email statistics by mailbox provider. - tags: - - Stats - 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). - 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 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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' + type: object + properties: + result: + type: array + items: + type: object + properties: + id: + type: string + description: Export jobs ID. + status: + type: string + description: 'Allowed values: `pending`, `ready`, or `failure`.' + created_at: + type: string + description: This ISO8601 timestamp when the export was created. + completed_at: + type: string + description: This ISO8601 timestamp when the export was completed. + expires_at: + type: string + description: This ISO8601 timestamp when the export expires. + urls: + type: array + description: One or more download URLs for the contact file(s) if the status is `ready`. + items: + type: string + user_id: + type: string + description: User ID. + export_type: + type: string + description: 'Allowed types: `contacts_export`, `list_export`, or `segment_export`.' + segments: + type: array + items: + type: object + properties: + ID: + type: string + Name: + type: string + lists: + type: array + items: + type: object + properties: + ID: + type: string + Name: + type: string + _metadata: + type: object + properties: + prev: + type: string + self: + type: string + next: + type: string + _metadata: + type: object + properties: + prev: + type: string + self: + type: string + description: Link to this page. + next: + type: string + description: Link to next page. + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + '': + type: string + error_id: + type: string + required: + - message + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + '/marketing/contacts/{id}': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: GET_mc-contacts-id + summary: Get a Contact by ID + tags: + - Contacts + description: '**This endpoint returns the full details and all fields for the specified contact**.' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contact-details3' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + /marketing/contacts/search: + post: + operationId: POST_mc-contacts-search + summary: Search Contacts + tags: + - Contacts + description: |- + **Use this endpoint to locate contacts**. + + The request body's `query` field accepts valid [SGQL](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) for searching for a contact. + + Only the first 50 contacts that meet the search criteria will be returned. + + If the query takes longer than 20 seconds, a `408 Request Timeout` status will be returned. + + Formatting the `created_at` and `updated_at` values as Unix timestamps is deprecated. Instead they are returned as ISO format as string. + parameters: + - name: body + in: body + schema: + type: object + properties: + query: + type: string + Description: An SGQL search string or other pattern. + required: + - query + example: + query: 'email LIKE ''ENTER_COMPLETE_OR_PARTIAL_EMAIL_ADDRESS_HERE%'' AND CONTAINS(list_ids, ''YOUR_LIST_IDs'')' + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/contact-details3' + _metadata: + $ref: '#/definitions/selfmetadata' + contact_count: + type: number + description: The total number of contacts matched. + required: + - contact_count + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '408': + description: '' + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + security: + - Authorization: [] + /marketing/contacts/imports: + put: + operationId: PUT_mc-contacts-imports + summary: Import Contacts + tags: + - Contacts + description: |- + **This endpoint allows a CSV upload containing up to one million contacts or 5GB of data, whichever is smaller.** + + Imports take place asynchronously: the endpoint returns a URL (`upload_uri`) and HTTP headers (`upload_headers`) which can subsequently be used to `PUT` a file of contacts to be imported into our system. + + Uploaded CSV files may also be [gzip-compressed](https://en.wikipedia.org/wiki/Gzip). + + In either case, you must include the field `file_type` with the value `csv` in your request body. + + The `field_mappings` paramter is a respective list of field definition IDs to map the uploaded CSV columns to. It allows you to use CSVs where one or more columns are skipped (`null`) or remapped to the contact field. + + For example, if `field_mappings` is set to `[null, "w1", "_rf1"]`, this means skip column 0, map column 1 to the custom field with the ID `w1`, and map column 2 to the reserved field with the ID `_rf1`. See #endpoint:ShdXXCcwwTE39zYAT to fetch your custom and reserved field IDs to use with `field_mappings`. + + Once you recieve the response body you can then initiate a **second** API call where you use the supplied URL and HTTP header to upload your file. For example: + + `curl --upload-file "file/path.csv" "URL_GIVEN" -H 'HEADER_GIVEN'` + + If you'd like to monitor the status of your import job, use the `job_id` and the #endpoint:m5WnoiseMvTXuNwZt endpoint. + parameters: + - name: body + in: body + schema: + type: object + properties: + list_ids: + type: array + description: All contacts will be added to each of the specified lists. + items: + type: string + file_type: + type: string + enum: + - csv + description: Upload file type. + field_mappings: + type: array + description: Import file header to reserved/custom field mapping. + uniqueItems: false + minItems: 1 + items: + anyOf: + - type: string + - type: 'null' + required: + - file_type + - field_mappings + responses: + '200': + description: '' + schema: + type: object + properties: + job_id: + type: string + description: The ID of the import job. + upload_uri: + type: string + description: The URI to PUT the upload file to. + upload_headers: + type: array + description: A list of headers that must be included in PUT request. + items: + type: object + properties: + header: + type: string + value: + type: string + required: + - header + - value + '400': + description: '' + schema: + type: object + uniqueItems: true + properties: + errors: + type: array + uniqueItems: true + items: + $ref: '#/definitions/error' + required: + - errors + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + type: object + description: If any of the specified lists do not exist. + uniqueItems: true + properties: + errors: + type: array + uniqueItems: true + items: + $ref: '#/definitions/error' + required: + - errors + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + '/marketing/contacts/imports/{id}': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: GET_marketing-contacts-imports-id + summary: Import Contacts Status + tags: + - Contacts + description: |- + **This endpoint can be used to check the status of a contact import job**. + + Use the `job_id` from the #endpoint:LPe3yJSpmGyv39oTa, #endpoint:rAGcTKvL5Q3XQd8Xp, or #endpoint:oazoY5DJsLqGMPfNY as the `id` in the path parameter. + + If there is an error with your `PUT` request, download the `errors_url` file and open it to view more details. + + The job `status` field indicates whether the job is `pending`, `completed`, `errored`, or `failed`. + + Pending means not started. Completed means finished without any errors. Errored means finished with some errors. Failed means finshed with all errors, or the job was entirely unprocessable: for example, if you attempt to import file format we do not support. + + The `results` object will have fields depending on the job type. + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contact-import' + '400': + description: '' + schema: + type: object + properties: + errors: + $ref: '#/definitions/error' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + '/marketing/contacts/exports/{id}': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: GET_mc-contacts-exports-id + summary: Export Contacts Status + tags: + - Contacts + description: |- + **This endpoint can be used to check the status of a contact export job**. + + To use this call, you will need the `id` from the #endpoint:aQ42cqyfw3XHCMdfY call. + + If you would like to download a list, take the `id` that is returned from #endpoint:aQ42cqyfw3XHCMdfY and make an API request here to get the `urls`. Once you have the list of URLs, make a `GET` request on each URL to download your CSV file(s). + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contact-export' + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + $ref: '#/definitions/error' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + /marketing/contacts/batch: + post: + operationId: POST_marketing-contacts-batch + summary: Get Batched Contacts by IDs + tags: + - Contacts + description: |- + **This endpoint is used to retrieve a set of contacts identified by their IDs.** + + This can be more efficient endpoint to get contacts than making a series of individual `GET` requests to #endpoint:f8xTRGmJGQ5bsgGaR. + + You can supply up to 100 IDs. Pass them into the `ids` field in your request body as an array or one or more strings. + parameters: + - name: body + in: body + schema: + type: object + description: Array of IDs + properties: + ids: + maxLength: 100 + type: array + items: + type: string + required: + - ids + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/contact-details3' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + type: object + '500': + $ref: '#/responses/trait:globalErrors:500' + /marketing/contacts/search/emails: + post: + operationId: POST_marketing-contacts-search-emails + summary: Get Contacts by Emails + tags: + - Contacts + description: |- + **This endpoint allows you to retrieve up to 100 contacts matching the searched `email` address(es), including any `alternate_emails`.** + + Email addresses are unique to a contact, meaning this endpoint can treat an email address as a primary key to search by. The contact object associated with the address, whether it is their `email` or one of their `alternate_emails` will be returned if matched. + + Email addresses are not case sensitive, and returned email addresses will be all lower case. Empty strings are excluded from the search and will not be returned. + + This endpoint should be used in place of the #endpoint:5oj27hT9p3TLXNBJP endpoint when you can provide exact email addresses and do not need to include other [Segmentation Query Language (SGQL)](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/) filters when searching. + + If you need to access a large percentage of your contacts, we recommend exporting your contacts with the #endpoint:aQ42cqyfw3XHCMdfY endpoint and filtering the results client side. + + This endpoint returns a `200` status code when any contacts match the address(es) you supplied. When searching multiple addresses in a single request, it is possible that some addresses will match a contact while others will not. When a partially successful search like this is made, the matching contacts are returned in an object and an error message is returned for the email address(es) that are not found. + + This endpoint returns a `404` status code when no contacts are found for the provided email address(es). + + A `400` status code is returned if any searched addresses are invalid. + parameters: + - name: body + in: body + schema: + type: object + description: '' + properties: + emails: + type: array + description: One or more primary emails and/or alternate emails to search through your contacts for. + items: + type: string + maxLength: 100 + required: + - emails + example: + emails: + - jane_doe@example.com + - john_doe@example.com + - joann_doe@example.com + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: object + additionalProperties: false + patternProperties: + '^[A-Za-z0-9\._%\+-]+@[A-Za-z0-9\.-]+\.[A-Za-z]{2,6}$': + type: object + description: This will be one of the specified email adresses. + properties: + contact: + $ref: '#/definitions/contact-details3' + error: + type: string + examples: + application/json: + result: + jane_doe@example.com: + contact: + address_line_1: '' + address_line_2: '' + alternate_emails: + - janedoe@example1.com + city: '' + country: '' + email: jane_doe@example.com + first_name: Jane + id: asdf-Jkl-zxCvBNm + last_name: Doe + list_ids: [] + segment_ids: [] + postal_code: '' + state_province_region: '' + phone_number: '' + whatsapp: '' + line: '' + facebook: '' + unique_name: '' + custom_fields: {} + created_at: '2021-03-02T15:25:47Z' + updated_at: '2021-03-30T15:26:16Z' + _metadata: + self: + john_doe@example.com: + contact: + address_line_1: '' + address_line_2: '' + alternate_emails: [] + city: '' + country: '' + email: john_doe@example.com + first_name: Jane + id: asdf-Jkl-qWeRTy + last_name: Doe + list_ids: [] + segment_ids: [] + postal_code: '' + state_province_region: '' + phone_number: '' + whatsapp: '' + line: '' + facebook: '' + unique_name: '' + custom_fields: {} + created_at: '2020-01-02T15:25:47Z' + updated_at: '2020-12-20T15:26:16Z' + _metadata: + self: + joann_doe@example.com: + error: contact not found + '400': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + security: + - Authorization: [] + /marketing/senders: + post: + operationId: POST_marketing-senders + summary: Create a Sender Identity + tags: + - Senders + description: |- + **This endpoint allows you to create a new sender identity.** + + *You may create up to 100 unique sender identities.* + + Sender identities are required to be verified before use. If your domain has been authenticated, a new sender identity will auto verify on creation. Otherwise an email will be sent to the `from.email`. + parameters: + - name: body + in: body + schema: + type: object + properties: + nickname: + type: string + description: A nickname for the sender identity. Not used for sending. + from: + type: object + required: + - email + - name + properties: + email: + type: string + description: This is where the email will appear to originate from for your recipient + name: + type: string + description: This is the name appended to the from email field. IE - Your name or company name. + reply_to: + type: object + properties: + email: + type: string + description: This is the email that your recipient will reply to. + name: + type: string + description: This is the name appended to the reply to email field. IE - Your name or company name. + required: + - email + address: + type: string + description: The physical address of the sender identity. + address_2: + type: string + description: Additional sender identity address information. + city: + type: string + description: The city of the sender identity. + state: + type: string + description: The state of the sender identity. + zip: + type: string + description: The zipcode of the sender identity. + country: + type: string + description: The country of the sender identity. + required: + - nickname + - from + - address + - city + - country + example: + nickname: Example Orders + from: + email: orders@example.com + name: Example Orders + reply_to: + email: support@example.com + name: Example Support + address: 1234 Fake St. + address_2: '' + city: San Francisco + state: CA + zip: '94105' + country: United States + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': + description: '' + schema: + $ref: '#/definitions/senderID' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + /marketing/lists: + post: + operationId: POST_mc-lists + summary: Create List + tags: + - Lists + description: |- + **This endpoint creates a new contacts list.** + + Once you create a list, you can use the UI to [trigger an automation](https://sendgrid.com/docs/ui/sending-email/getting-started-with-automation/#create-an-automation) every time you add a new contact to the list. + + A link to the newly created object is in `_metadata`. + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: Your name for your list + minLength: 1 + maxLength: 100 + required: + - name + example: + name: list-name + responses: + '200': + description: '' + schema: + $ref: '#/definitions/list' + examples: + application/json: + id: ca7a3796-e8a8-4029-9ccb-df8937940562 + name: list-name + contact_count: 0 + _metadata: + self: 'https://api.sendgrid.com/v3/marketing/lists/ca7a3796-e8a8-4029-9ccb-df8937940562' + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + $ref: '#/definitions/error' + security: + - Authorization: [] + get: + operationId: GET_mc-lists + summary: Get All Lists + tags: + - Lists + description: '**This endpoint returns an array of all of your contact lists.**' + parameters: + - name: page_size + in: query + description: 'Maximum number of elements to return. Defaults to 100, returns 1000 max' + required: false + type: number + default: 100 + minimum: 1 + maximum: 1000 + - name: page_token + in: query + required: false + type: string + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/list' + _metadata: + $ref: '#/definitions/metadata' + examples: + application/json: + result: + - id: abc12312-x3y4-1234-abcd-123qwe456rty + name: list-name + contact_count: 0 + _metadata: + self: 'https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty' + _metadata: + self: 'https://api.sendgrid.com/v3/marketing/lists?page_size=100&page_token=' + security: + - Authorization: [] + '/marketing/lists/{id}/contacts/count': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: GET_mc-lists-id-contacts-count + summary: Get List Contact Count + tags: + - Lists + description: '**This endpoint returns the number of contacts on a specific list.**' + responses: + '200': + description: '' + schema: + type: object + properties: + contact_count: + type: integer + billable_count: + type: integer + examples: + application/json: + contact_count: 0 + 'billable_count:': 0 + '404': + description: '' + schema: + type: object + security: + - Authorization: [] + '/marketing/lists/{id}': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: GET_mc-lists-id + summary: Get a List by ID + tags: + - Lists + description: |- + **This endpoint returns data about a specific list.** + + Setting the optional parameter `contact_sample=true` returns the `contact_sample` in the response body. Up to fifty of the most recent contacts uploaded or attached to a list will be returned, sorted alphabetically, by email address. + + The full contact count is also returned. + parameters: + - name: contact_sample + in: query + description: Setting this parameter to the true will cause the contact_sample to be returned + type: boolean + default: false + responses: + '200': + description: '' + schema: + allOf: + - $ref: '#/definitions/list' + - type: object + properties: + contact_sample: + $ref: '#/definitions/contact-details2' + examples: + application/json: + contact_count: 2 + contact_sample: + id: c3445f88-5c69-4237-86e6-9ec9de958050 + list_ids: + - 199abb98-0af3-4a8d-b371-6811ff85d062 + created_at: '2620-06-16T17:03:54.867Z' + updated_at: '4780-12-06T06:51:30.024Z' + _metadata: + self: 'https://api.sendgrid.com/v3/marketing/lists/199abb98-0af3-4a8d-b371-6811ff85d062' + id: 199abb98-0af3-4a8d-b371-6811ff85d062 + name: list-name + '404': + description: '' + schema: + type: array + items: + $ref: '#/definitions/error' + security: + - Authorization: [] + patch: + operationId: PATCH_mc-lists-id + summary: Update List + tags: + - Lists + description: '**This endpoint updates the name of a list.**' + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: Your name for your list. + example: + name: updated-list-name + responses: + '200': + description: '' + schema: + $ref: '#/definitions/list' + examples: + application/json: + id: abc12312-x3y4-1234-abcd-123qwe456rty + name: updated-list-name + contact_count: 0 + _metadata: + self: 'https://api.sendgrid.com/v3/marketing/lists/abc12312-x3y4-1234-abcd-123qwe456rty' + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + $ref: '#/definitions/error' + '404': + description: '' + schema: + type: object + security: + - Authorization: [] + delete: + operationId: DELETE_lists-id + summary: Delete a list + tags: + - Lists + description: |- + **This endpoint allows you to deletes a specific list.** + + Optionally, you can also delete contacts associated to the list. The query parameter, `delete_contacts=true`, will delete the list and start an asynchronous job to delete associated contacts. + parameters: + - name: delete_contacts + in: query + description: Flag indicates that all contacts on the list are also to be deleted. + required: false + type: boolean + default: false + responses: + '200': + description: '' + schema: + type: object + description: The delete has been accepted and is processing. + properties: + job_id: + type: string + description: job_id of the async job + examples: + application/json: + job_id: abc12312-x3y4-1234-abcd-123qwe456rty + '204': + description: '' + schema: + type: string + description: 'The delete has been processed. ' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + required: + - errors + security: + - Authorization: [] + '/marketing/lists/{id}/contacts': + parameters: + - name: id + in: path + required: true + type: string + delete: + operationId: DELETE_mc-lists-id-contacts + summary: Remove Contacts from a List + tags: + - Lists + description: |- + **This endpoint allows you to remove contacts from a given list.** + + The contacts will not be deleted. Only their list membership will be changed. + parameters: + - name: contact_ids + in: query + description: comma separated list of contact ids + required: true + type: string + minLength: 1 + responses: + '202': + description: '' + schema: + type: object + description: The removal is accepted and processing. + properties: + job_id: + type: string + description: job_id of the async job + '400': + description: '' + schema: + $ref: '#/definitions/error' + '404': + description: '' + schema: + description: If the specified list id does not exist. If the specified contact does not exist. + security: + - Authorization: [] + /marketing/field_definitions: + post: + operationId: POST_mc-field_definitions + summary: Create Custom Field Definition + tags: + - Custom Fields + description: |- + **This endpoint creates a new custom field definition.** + + Custom field definitions are created with the given `name` and `field_type`. Although field names are stored in a case-sensitive manner, all field names must be case-insensitively unique. This means you may create a field named `CamelCase` or `camelcase`, but not both. Additionally, a Custom Field name cannot collide with any Reserved Field names. You should save the returned `id` value in order to update or delete the field at a later date. You can have up to 120 custom fields. + + The custom field name should be created using only alphanumeric characters (A-Z and 0-9) and underscores (\_). Custom fields can only begin with letters A-Z or underscores (_). The field type can be date, text, or number fields. The field type is important for creating segments from your contact database. + + **Note: Creating a custom field that begins with a number will cause issues with sending in Marketing Campaigns.** + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + field_type: + type: string + enum: + - Text + - Number + - Date + required: + - name + - field_type + example: + name: custom_field_name + field_type: Text + responses: + '200': + description: '' + schema: + allOf: + - $ref: '#/definitions/custom_field_definitions_response' + - type: object + properties: + _metadata: + $ref: '#/definitions/_metadata' + examples: + application/json: + id: a1_T + name: custom_field_name + field_type: Text + _metadata: + self: 'https://api.sendgrid.com/v3/marketing/field_definitions/a1_B' + '400': + description: '' + schema: + type: object + uniqueItems: true + properties: + errors: + type: array + uniqueItems: true + items: + $ref: '#/definitions/error' + required: + - errors + security: + - Authorization: [] + get: + operationId: GET_mc-field_definitions + summary: Get All Field Definitions + tags: + - Custom Fields + description: '**This endpoint retrieves all defined Custom Fields and Reserved Fields.**' + responses: + '200': + description: '' + schema: + type: object + uniqueItems: true + properties: + custom_fields: + type: array + minitems: 0 + manitems: 120 + items: + $ref: '#/definitions/custom_field_definitions_response' + reserved_fields: + $ref: '#/definitions/reserved_field_definitions_response' + _metadata: + $ref: '#/definitions/_metadata' + required: + - custom_fields + - reserved_fields + examples: + application/json: + custom_fields: + - id: w1 + name: num_orders + field_type: Number + - id: w2 + name: dob + field_type: Date + reserved_fields: + - id: _rf0_T + name: first_name + field_type: Text + - id: _rf1_T + name: last_name + field_type: Text + - id: _rf2_T + name: email + field_type: Text + - id: _rf3_T + name: alternate_emails + field_type: Text + - id: _rf4_T + name: address_line_1 + field_type: Text + - id: _rf5_T + name: address_line_2 + field_type: Text + - id: _rf6_T + name: city + field_type: Text + - id: _rf7_T + name: state_province_region + field_type: Text + - id: _rf8_T + name: postal_code + field_type: Text + - id: _rf9_T + name: country + field_type: Text + - id: _rf10_T + name: phone_number + field_type: Text + - id: _rf11_T + name: whatsapp + field_type: Text + - id: _rf12_T + name: line + field_type: Text + - id: _rf13_T + name: facebook + field_type: Text + - id: _rf14_T + name: unique_name + field_type: Text + - id: _rf15_T + name: email_domains + field_type: Text + read_only: true + - id: _rf16_D + name: last_clicked + field_type: Date + read_only: true + - id: _rf17_D + name: last_opened + field_type: Date + read_only: true + - id: _rf18_D + name: last_emailed + field_type: Date + read_only: true + - id: _rf19_T + name: singlesend_id + field_type: Text + read_only: true + - id: _rf20_T + name: automation_id + field_type: Text + read_only: true + - id: _rf21_D + name: created_at + field_type: Date + read_only: true + - id: _rf22_D + name: updated_at + field_type: Date + read_only: true + - id: _rf23_T + name: contact_id + field_type: Text + read_only: true + _metadata: + self: 'https://example.com/marketing/field_definitions' + security: + - Authorization: [] + '/marketing/field_definitions/{custom_field_id}': + parameters: + - name: custom_field_id + in: path + required: true + type: string + patch: + operationId: PATCH_mc-field_definitions-custom_field_id + summary: Update Custom Field Definition + tags: + - Custom Fields + description: |- + **This endopoint allows you to update a defined Custom Field.** + + Only your Custom fields can be modified; Reserved Fields cannot be updated. + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + required: + - name + example: + name: new_custom_field_name + responses: + '200': + description: '' + schema: + allOf: + - $ref: '#/definitions/custom_field_definitions_response' + - type: object + properties: + _metadata: + $ref: '#/definitions/_metadata' + examples: + application/json: + id: a1_T + name: custom_field_name + field_type: Text + _metadata: + self: 'https://api.sendgrid.com/v3/marketing/field_definitions/a1_B' + '400': + description: '' + schema: + type: object + uniqueItems: true + properties: + errors: + type: array + uniqueItems: true + items: + $ref: '#/definitions/error' + required: + - errors + '404': + description: '' + schema: + type: object + uniqueItems: true + properties: + errors: + type: array + uniqueItems: true + items: + $ref: '#/definitions/error' + required: + - errors + security: + - Authorization: [] + delete: + operationId: DELETE_mc-field_definitions-custom_field_id + summary: Delete Custom Field Definition + tags: + - Custom Fields + description: |- + **This endpoint deletes a defined Custom Field.** + + You cand delete only Custom Fields; Reserved Fields cannot be deleted. + responses: + '204': + description: '' + '404': + description: '' + schema: + type: object + required: + - errors + properties: + errors: + type: array + uniqueItems: true + items: + $ref: '#/definitions/error' + security: + - Authorization: [] + /marketing/segments: + post: + operationId: POST_marketing-segments + summary: Create Segment + tags: + - segmenting contacts + - Segmenting Contacts + description: '**This endpoint allows you to create a segment.**' + parameters: + - name: body + in: body + schema: + allOf: + - $ref: '#/definitions/segment_write' + - type: object + properties: + parent_list_id: + type: string + minLength: 36 + maxLength: 36 + format: uuid + description: 'The id of the list if this segment is a child of a list. This implies the query is rewritten as `(${query_dsl}) AND CONTAINS(list_ids, ${parent_list_id})`' + responses: + '201': + description: '' + schema: + $ref: '#/definitions/full-segment' + examples: + application/json: + id: 864feb2e-5e93-47bf-b63e-21746c988105 + contacts_count: 0 + created_at: mollit labore aute deserunt ad + sample_updated_at: enim culpa in + updated_at: minim + contact_summary: + contact_id: 1a541ca7-9fef-42c8-8947-f3f8a3b33ffe + primary_email: D8OsYF5ok@YtX.kcg + first_name: exercitation Duis nisi + last_name: aut + address_line_1: ut sunt Duis eu + address_line_2: in culpa esse non + city: ÔXƫɋƄř + state_province_region: consequat culpa in + postal_code: -88086402 + country: eiusmod + custom_fields: + custom_field_name2: dolore cillum + custom_field_name1: est mollit officia adipisicing dolo + list_ids: + - c856a255-12f1-4b55-8564-218fd7eb34a7 + - 130c8813-0d6f-4b9e-b154-736bb9db2ff8 + - c245021d-4444-4086-a498-3ffee7fa8cdf + name: aute amet deserunt adipisicing + query_dsl: email LIKE %twilio.com + next_sample_update: culpa sit occaecat fugiat quis + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + required: + - message + required: + - errors + security: + - Authorization: [] + get: + operationId: GET_marketing-segments + summary: Get List of Segments + tags: + - segmenting contacts + - Segmenting Contacts + description: |- + **This endpoint allows you to retrieve a list of segments.** + + The query param `parent_list_ids` is treated as a filter. Any match will be returned. 0 matches will return a response code of 200 with an empty `results` array. + + `parent_list_ids` | `no_parent_list_id` | `result` + -----------------:|:--------------------:|:------------- + empty | false | all segments + values | false | segments filtered by list_ids + values | true | segments filtered by list_ids and segments with no parent list_ids + empty | true | segments with no parent list_ids + parameters: + - name: parent_list_ids + in: query + description: 'A comma separated list of list ids to be used when searching for segments with the specified parent_list_id, no more than 50 is allowed' + type: string + - name: no_parent_list_id + in: query + description: If set to `true` segments with an empty value of `parent_list_id` will be returned in the filter. If the value is not present it defaults to 'false'. + type: boolean + default: false + responses: + '200': + description: '' + schema: + type: object + properties: + results: + type: array + uniqueItems: true + minItems: 0 + items: + $ref: '#/definitions/segment_summary' + required: + - results + examples: + application/json: + results: + - id: 12099613-91e5-4d09-a900-df7626325288 + contacts_count: 78434802 + created_at: '2921-01-27T19:33:36.479Z' + sample_updated_at: '4685-11-26T07:05:04.660Z' + updated_at: '2883-07-10T13:13:37.697Z' + - id: 60c37015-3734-4c8e-b293-68cfa2ae4fa5 + contacts_count: 34177253 + created_at: '2575-07-26T23:17:20.984Z' + sample_updated_at: '3074-09-04T09:49:58.127Z' + updated_at: '5116-10-15T07:37:40.838Z' + parent_list_id: fd38af3d-3f69-4947-8dca-5fa967e7be82 + name: amet + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + required: + - message + required: + - errors + security: + - Authorization: [] + '/marketing/segments/{segment_id}': + parameters: + - name: segment_id + in: path + required: true + type: string + minLength: 36 + maxLength: 36 + format: uuid + get: + operationId: GET_marketing-segments-segment_id + summary: Get Segment by ID + tags: + - segmenting contacts + - Segmenting Contacts + description: '**This endpoint allows you to retrieve a single segment by ID.**' + parameters: + - name: query_json + in: query + description: Defaults to `false`. Set to `true` to return the parsed SQL AST as a JSON object in the field `query_json` + type: boolean + responses: + '200': + description: '' + schema: + $ref: '#/definitions/full-segment' + examples: + application/json: + id: 3b049926-0a54-4a91-83f0-086ace63c530 + contacts_count: -83213117 + created_at: voluptate sunt non fugiat + sample_updated_at: labore occaecat sunt enim + updated_at: sunt aliqui + contacts_sample: + - contact_id: e70eac25-1431-4231-bccd-1cfab432301e + primary_email: KLTF@SurgGzlAxCPOqhOUHYNBLsfpfE.trh + alternate_emails: + - dTeJZgU5uN9UYSo@nfIB.ijxg + first_name: ullamco esse culpa do + last_name: officia laboris veniam consequat + address_line_1: in occaecat labore est tempor + address_line_2: magna adipisicing + city: ƞó + state_province_region: culpa ut + postal_code: -75218567 + country: voluptate in in reprehenderit aliquip + custom_fields: + custom_field_name1: amet deserunt mollit + custom_field_name2: minim consequat id + - contact_id: db637d33-bce1-462c-ae9c-91ec4f761de6 + primary_email: t7N5TjDmKhC0@gfdifW.ua + alternate_emails: + - gQol@Xcfilli.hc + - n4K7OdaVQh@YfsnF.ie + - TdnvS3nMStREn@miFjGzNDCPZWhiswJNxrFnOYdUAZEpesQ.yxpu + - xRzGDTTzzbYK@eJ.wpgb + - iI1rOpx2ct@aZhuYGZBxJLZ.phr + first_name: ea et eu + last_name: velit Ut laborum ipsu + address_line_1: labore + address_line_2: non + city: "Ĕȸą\x9F¸ȠɏbɄ" + state_province_region: deserunt dolore + postal_code: -95171713 + country: do + list_ids: + - c712288b-2300-4069-bef4-2e05b5948ec3 + - 9003ef29-5eb7-4951-898b-1b102e490d6e + name: enim et anim + query_dsl: nostrud + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + required: + - message + - field + required: + - errors + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + required: + - message + required: + - errors + security: + - Authorization: [] + patch: + operationId: PATCH_marketing-segments-segment_id + summary: Update Segment + tags: + - segmenting contacts + - Segmenting Contacts + description: |- + **This endpoint allows you to update a segment.** + + Segment `name` needs to be unique. A user can not update a segment name to an existing one. + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/segment_write' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/full-segment' + examples: + application/json: + id: 5fff6250-b766-4959-a183-2e1fa565c4ce + contacts_count: -35493018 + created_at: '2014-12-23T17:18:52.907Z' + sample_updated_at: '2146-04-13T16:46:32.328Z' + updated_at: '4389-06-21T16:59:51.403Z' + contacts_sample: + - contact_id: 4cff9fdf-1bee-44f7-95dc-a101f9ed3cfe + primary_email: exmS@KIzibBSmaUUHQa.uvv + alternate_emails: + - qXP-RD97fLl@oEDaUynqnNRHJHdoJAWVGXwvI.qlv + - W0ngFWmR@WcQuSbPFVPZvLrjCFadfimFi.eqf + - mYBC0ea5UxFI@qwO.jh + - Nhf1OmY@KCSjTQsXYpbKrBUsQFHrnLuY.oef + first_name: consequat nulla in + last_name: irure nostrud elit eu + address_line_1: deserunt cillum aliqua nostrud ullamco + address_line_2: sint + city: ŷ(ç + state_province_region: minim + postal_code: 62721676 + country: consectetur quis voluptate + list_ids: + - f9d5987d-7a01-4a66-b77e-1f08a392304b + - b4e3b028-01d4-428b-9ef5-24bcd90fa02c + - fedab84f-9aa5-449d-99e2-7b1361f8ee61 + - contact_id: 093a66b8-bca8-4d8a-b32a-091d939c1928 + primary_email: atNeYGC4nbF42@VOCUWuGaYr.ystm + alternate_emails: + - Zs6vnQbMU@XTamDsXEGJWBMMEacOc.hitv + - Epl@ySBrQCFJZnjggkAYLu.ppta + first_name: est + last_name: in + address_line_1: culpa eu eiusmod sint + address_line_2: sed velit sint + city: BĊJ + state_province_region: Lorem Ut aliqua elit + postal_code: 33736880 + country: in laboris Excepteur consequat + custom_fields: + custom_field_name2: culpa Excepteur + custom_field_name1: esse magna Ut + - contact_id: 08939f9c-2c87-4639-bd07-16d41f90a5eb + primary_email: Jx660QHClqRrC@SavQvcdRpJlLqepwoEUCm.ar + alternate_emails: + - S8u@ZVGjHsXdSWtlhhad.ximc + - GA1MN72v3uA@MPDvMUmTYjwFCsEaGnFnvVzJVqUTl.ehws + first_name: sed eu veli + last_name: aliqua sit culpa + address_line_1: occaecat aute enim + address_line_2: ipsum quis in + city: ɌſĕĝȤ¶Ǖ + state_province_region: ut nisi sed esse + postal_code: -66445052 + country: occaecat veniam + - contact_id: 0667ed97-7b7b-44aa-a115-0301067660d7 + primary_email: AnoFtJq@IolRDmfj.njt + alternate_emails: + - F5WhHCA3oL6Ix@wOKzwIsvHbFi.mrlc + first_name: do mollit velit + last_name: voluptate dolor + address_line_1: et incididunt + address_line_2: veniam quis non exercitation Duis + city: DzƐȹŲdž + state_province_region: occaecat + postal_code: -19694583 + country: reprehenderit + custom_fields: + custom_field_name1: dolor aute irure Excepteur + list_ids: + - ffd225a8-2008-4457-87af-1cffff5b1ccb + - contact_id: 449767ca-d446-45f1-aa9b-432f441b5ca1 + primary_email: kF4@gYYdAxzetJrWszLAHuBUTu.rzq + alternate_emails: + - ksqbx6BInlB@ouWBjjxwFBwVQjdnEKXy.xi + - TAe7F2m8dFlF@SirYykzbe.aj + - T9c2Y@HjVQY.zz + - p7ShfET@vMMnTUqoqngPSEqbpyoeWN.jlqn + - 0VJSIhIUT2k@mJXVtdZVKKswW.xoca + first_name: irure laboris minim + last_name: id nostrud aliqua sit + address_line_1: dolor + address_line_2: elit ex labore sunt aliquip + city: "ÝǘźƝǝƉ\x91Ɲ\x90" + state_province_region: nostrud Duis non nulla laborum + postal_code: 60466925 + country: id sunt nisi + custom_fields: + custom_field_name2: enim quis + custom_field_name1: amet + list_ids: + - 2870627c-b9ea-4dcf-bde0-36c3e0e3eca9 + - 575d86aa-4dcc-4b7d-b7de-ded856913198 + - fb82a17f-5777-439d-9b8c-2c565c8ddf20 + name: List Name + query_dsl: Email LIKE %twilio.com + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + required: + - message + - field + required: + - errors + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + required: + - message + required: + - errors + security: + - Authorization: [] + delete: + operationId: DELETE_marketing-segments-segment_id + summary: Delete Segment + tags: + - segmenting contacts + - Segmenting Contacts + description: |- + **This endpoint allows you to delete a segment by `segment_id`.** + + Note that deleting a segment does not delete the contacts associated with the segment by default. Contacts associated with a deleted segment will remain in your list of all contacts and any other segments they belong to. + responses: + '202': + description: '' + schema: + type: object + '400': + description: '' + schema: + $ref: '#/definitions/error_schema' + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + required: + - message + - field + required: + - errors + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + required: + - message + required: + - errors + security: + - Authorization: [] + /marketing/segments/delete: + post: + operationId: POST_marketing-segments-delete + summary: Bulk Delete Segments + tags: + - Segmenting Contacts + description: |- + This endpoint allows you to delete segments in bulk. + + If the segments are used by automations or the segments do not exist in the database, the segment IDs that could not be deleted along with automation IDs that are associated to those segments will be returned. + parameters: + - name: body + in: body + schema: + type: object + properties: + ids: + type: array + items: + type: string + format: uuid + example: + ids: + - a14dcc63-d651-4c57-9826-4a3705f5c78d + - f3de551e-dc5c-4d42-bd08-c7f87f87f0e8 + - 1b8107b5-adf4-401c-8865-fa84ba178fb9 + - d7900715-c904-4728-acff-9ab79627579e + - 16641f5b-cfa3-41b9-9626-244488ee85b1 + responses: + '200': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + id: + type: string + description: Segment ID + error: + type: string + description: 'error message that indicates why segment cannot be deleted ("in-use", "segment not found", "invalid uuid")' + resources: + type: object + description: resources in which segment is being used + properties: + type: + type: string + description: 'the type of resource in use (e.g., "automation")' + ids: + type: array + description: the resource ids + items: + type: string + '202': + description: '' + schema: + type: object + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + /marketing/singlesends: + post: + operationId: POST_marketing-singlesends + summary: Create Single Send + tags: + - Single Sends + description: |- + **This endpoint allows you to create a new Single Send.** + + Please note that if you are migrating from the previous version of Single Sends, you no longer need to pass a template ID with your request to this endpoint. Instead, you will pass all template data in the `email_config` object. + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/singlesend_request' + example: + name: Example API Created Single Send + categories: + - unique opens + send_to: + all: true + email_config: + design_id: + editor: design + suppression_group_id: 12345 + sender_id: 1234567 + responses: + '201': + description: '' + schema: + $ref: '#/definitions/singlesend_response' + examples: + application/json: + name: Example API Created Single Send + id: 27c21bbf-a12c-440b-b8bf-c526975328ca + status: scheduled + created_at: '2020-05-18T17:28:27.272Z' + send_at: '2020-06-16T00:19:55.106Z' + categories: + - unique opens + email_config: + subject: '' + html_content: '' + plain_content: '' + generate_plain_content: true + editor: code + suppression_group_id: null + custom_unsubscribe_url: null + sender_id: null + ip_pool: null + send_to: + list_ids: + - f2fe66a1-43f3-4e3a-87b1-c6a600d805f0 + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + get: + operationId: GET_marketing-singlesends + summary: Get All Single Sends + tags: + - Single Sends + description: |- + **This endpoint allows you to retrieve all your Single Sends.** + + Returns all of your Single Sends with condensed details about each, including the Single Sends' IDs. For more details about an individual Single Send, pass the Single Send's ID to the `/marketing/singlesends/{id}` endpoint. + parameters: + - name: page_size + in: query + type: integer + - name: page_token + in: query + type: string + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/singlesend_response_short' + _metadata: + $ref: '#/definitions/_metadata' + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + delete: + operationId: DELETE_marketing-singlesends + summary: Bulk Delete Single Sends + tags: + - Single Sends + description: |- + **This endpoint allows you to delete multiple Single Sends using an array of Single Sends IDs.** + + To first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint. + + Please note that a DELETE request is permanent, and your Single Sends will not be recoverable after deletion. + parameters: + - name: ids + in: query + description: Single Send IDs to delete + type: array + minItems: 1 + maxItems: 50 + items: + type: string + responses: + '204': + description: '' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + '/marketing/singlesends/{id}': + parameters: + - name: id + in: path + required: true + type: string + post: + operationId: POST_marketing-singlesends-id + summary: Duplicate Single Send + tags: + - Single Sends + description: |- + **This endpoint allows you to duplicate an existing Single Send using its Single Send ID.** + + Duplicating a Single Send is useful when you want to create a Single Send but don't want to start from scratch. Once duplicated, you can update or edit the Single Send by making a PATCH request to the `/marketing/singlesends/{id}` endpoint. + + If you leave the `name` field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text “Copy of ” prepended to it. The `name` field length is limited to 100 characters, so the end of the new Single Send name, including “Copy of ”, will be trimmed if the name exceeds this limit. + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + description: 'The name of the duplicate Single Send. If you choose to leave the name field blank, your duplicate will be assigned the name of the Single Send it was copied from with the text ''Copy of '' prepended to it. The end of the new Single Send name, including ''Copy of '', will be trimmed if the name exceeds the character limit.' + responses: + '201': + description: '' + schema: + $ref: '#/definitions/singlesend_response' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + patch: + operationId: PATCH_marketing-singlesends-id + summary: Update Single Send + tags: + - Single Sends + description: |- + **This endpoint allows you to update a Single Send using a Single Send ID.** + + You only need to pass the fields you want to update. Any blank/missing fields will remain unaltered. + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/singlesend_request' + responses: + '202': + description: '' + schema: + $ref: '#/definitions/singlesend_response' + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + get: + operationId: GET_marketing-singlesends-id + summary: Get Single Send by ID + tags: + - Single Sends + description: |- + **This endpoint allows you to retrieve details about one Single Send using a Single Send ID.** + + You can retrieve all of your Single Sends by making a GET request to the `/marketing/singlesends` endpoint. + responses: + '200': + description: '' + schema: + $ref: '#/definitions/singlesend_response' + examples: + application/json: + name: single-send-1 + id: 2f6dec81-43b9-4c67-a890-3a38cb63b54a + status: scheduled + created_at: '2020-12-13T16:24:42.013Z' + send_to: + segment_ids: + - dad84de3-bec4-4e04-b132-2cbfd4bb3789 + - 7dce758d-1155-4102-88d2-ca65565ac98b + all: true + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + delete: + operationId: DELETE_marketing-singlesends-id + summary: Delete Single Send by ID + tags: + - Single Sends + description: |- + **This endpoint allows you to delete one Single Send using a Single Send ID.** + + To first retrieve all your Single Sends' IDs, you can make a GET request to the `/marketing/singlensends` endpoint. + + Please note that a `DELETE` request is permanent, and your Single Send will not be recoverable after deletion. + responses: + '204': + description: '' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + /marketing/singlesends/search: + post: + operationId: POST_marketing-singlesends-search + summary: Get Single Sends Search + tags: + - Single Sends + description: |- + **This endpoint allows you to search for Single Sends based on specified criteria.** + + You can search for Single Sends by passing a combination of values using the `name`, `status`, and `categories` request body fields. + + For example, if you want to search for all Single Sends that are "drafts" or "scheduled" and also associated with the category "shoes," your request body may look like the example below. + + ```javascript + { + "status": [ + "draft", + "scheduled" + ], + "categories": [ + "shoes" + ], + } + ``` + parameters: + - name: page_size + in: query + type: integer + - name: page_token + in: query + type: string + - name: body + in: body + schema: + $ref: '#/definitions/singlesend_search' + example: + name: specific-single-send-name + status: + - draft + - scheduled + categories: + - shoes + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/singlesend_response_short' + _metadata: + $ref: '#/definitions/_metadata' + examples: + application/json: + result: + - id: df25ffdf-6a96-458a-9419-6d87d3094c6b + name: single-send-1 + status: triggered + categories: + - shoes + is_abtest: true + updated_at: '3263-04-09T09:05:08.193Z' + created_at: '4739-10-29T07:11:32.476Z' + send_at: '2471-05-31T15:46:18.797Z' + _metadata: + self: nwNSrPSWt7d + prev: P0Enoayd + next: DYEsTUDww9- + count: 1 + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + '/marketing/singlesends/{id}/schedule': + parameters: + - name: id + in: path + required: true + type: string + put: + operationId: PUT_marketing-singlesends-id-schedule + summary: Schedule Single Send + tags: + - Single Sends + description: |- + **This endpoint allows you to schedule a Single Send for future delivery using a Single Send ID.** + + To schedule a Single Send, you must pass a date string in ISO 8601 time format (yyyy-MM-ddTHH:mm:ssZ) using the required `send_at` field. For example, the ISO 8601 format for 9:00 AM UTC on May 6, 2020 would be `2020-05-06T09:00:00Z`. You may also pass the string `"now"` to send the Single Send immediately. + parameters: + - name: body + in: body + schema: + type: object + properties: + send_at: + type: string + description: 'This is the ISO 8601 time at which to send the Single Send; must be in future, or the string "now"' + enum: + - now + format: date-time + required: + - send_at + example: + send_at: now + responses: + '201': + description: '' + schema: + type: object + properties: + send_at: + type: string + format: date-time + status: + type: string + enum: + - scheduled + examples: + application/json: + send_at: now + status: scheduled + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + delete: + operationId: DELETE_marketing-singlesends-id-schedule + summary: Delete Single Send Schedule + tags: + - Single Sends + description: |- + **This endpoint allows you to cancel a scheduled Single Send using a Single Send ID.** + + Making a DELETE request to this endpoint will cancel the scheduled sending of a Single Send. The request will not delete the Single Send itself. Deleting a Single Send can be done by passing a DELETE request to `/marketing/singlesends/{id}`. + responses: + '200': + description: '' + schema: + $ref: '#/definitions/singlesend_schedule' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + /marketing/singlesends/categories: + get: + operationId: GET_marketing-singlesends-categories + summary: Get All Categories + tags: + - Single Sends + description: |- + **This endpoint allows you to retrieve all the categories associated with your Single Sends.** + + This endpoint will return your latest 1,000 categories. + responses: + '200': + description: '' + schema: + type: object + properties: + categories: + type: array + uniqueItems: true + maxItems: 1000 + description: list of latest one thousand unique categories associated with all Single Sends in ascending order + items: + type: string + examples: + application/json: + categories: + - equipment + - shoes + - sports + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + error_id: + type: string + security: + - Authorization: [] + /marketing/test/send_email: + post: + operationId: POST_marketing-test-send_email + summary: Send a Test Marketing Email + tags: + - Send Test Email + description: |- + **This endpoint allows you to send a test marketing email to a list of email addresses**. + + Before sending a marketing message, you can test it using this endpoint. You may specify up to **10 contacts** in the `emails` request body field. You must also specify a `template_id` and include either a `from_address` or `sender_id`. You can manage your templates with the [Twilio SendGrid App](https://mc.sendgrid.com/dynamic-templates) or the [Transactional Templates API](https://sendgrid.api-docs.io/v3.0/transactional-templates). + + > Please note that this endpoint works with Dynamic Transactional Templates only. Legacy Transactional Templates will not be delivered. + + For more information about managing Dynamic Transactional Templates, see [How to Send Email with Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/). + + You can also test your Single Sends in the [Twilio SendGrid Marketing Campaigns UI](https://mc.sendgrid.com/single-sends). + parameters: + - name: body + in: body + schema: + type: object + properties: + template_id: + type: string + format: uuid + description: 'The ID of the template that you would like to use. If you use a template that contains a subject and content (either text or HTML), then those values specified at the personalizations or message level will not be used.' + version_id_override: + type: string + format: uuid + description: ' You can override the active template with an alternative template version by passing the version ID in this field. If this field is blank, the active template version will be used.' + sender_id: + type: integer + description: 'This ID must belong to a verified sender. Alternatively, you may supply a `from_address` email.' + custom_unsubscribe_url: + type: string + description: A custom unsubscribe URL. + suppression_group_id: + type: integer + emails: + type: array + uniqueItems: true + minItems: 1 + maxItems: 10 + items: + type: string + format: email + description: An array of email addresses you want to send the test message to. + from_address: + type: string + description: You can either specify this address or specify a verified sender ID. + format: email + required: + - template_id + - emails + example: '{"template_id":"f8f77db8-b9fa-4b3c-9ee8-de3d582016b8","version_id_override":"","sender_id":6060664,"custom_unsubscribe_url":"esse Excepteur ","suppression_group_id":21865513,"emails":["janedoe@example.com","tiramisu@example.com","bundt@example.com"}' + responses: + '202': + description: '' + schema: + type: object + '400': + $ref: '#/responses/trait:errorResponse:400' + security: + - Authorization: [] + /marketing/stats/automations: + get: + operationId: getall-automation-stats + summary: Get All Automation Stats + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint allows you to retrieve stats for all your Automations.** + + By default, all of your Automations will be returned, but you can specify a selection by passing in a comma-separated list of Automation IDs as the value of the query string parameter `automation_ids`. + + Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. + + You can retrieve a specific page of responses with the `page_token` query string parameter. + parameters: + - name: automation_ids + in: query + description: This endpoint returns all automation IDs if no `automation_ids` are specified. + type: array + minItems: 1 + maxItems: 25 + items: + type: string + - $ref: '#/parameters/trait:pagination:page_size' + - $ref: '#/parameters/trait:pagination:page_token' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/automations-response' + '400': + description: '' + schema: + $ref: '#/definitions/error_schema' + security: + - Authorization: [] + '/marketing/stats/automations/{id}': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: get-automation-stat + summary: Get Automation Stats by ID + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint allows you to retrieve stats for a single Automation using its ID.** + + Multiple Automation IDs can be retrieved using the #endpoint:tMC3DWPZFRZKCx45d endpoint. Once you have an ID, this endpoint will return detailed stats for the single automation specified. + + You may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned. + parameters: + - $ref: '#/parameters/trait:automationQueryParams:group_by' + - $ref: '#/parameters/trait:automationQueryParams:step_ids' + - $ref: '#/parameters/trait:baseParams:aggregated_by' + - $ref: '#/parameters/trait:baseParams:start_date' + - $ref: '#/parameters/trait:baseParams:end_date' + - $ref: '#/parameters/trait:baseParams:timezone' + - $ref: '#/parameters/trait:pagination:page_size' + - $ref: '#/parameters/trait:pagination:page_token' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/automations-response' + '400': + $ref: '#/responses/trait:errorResponse:400' + '404': + description: '' + security: + - Authorization: [] + /marketing/stats/singlesends: + get: + operationId: getall-singlesend-stats + summary: Get All Single Sends Stats + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint allows you to retrieve stats for all your Single Sends.** + + By default, all of your Single Sends will be returned, but you can specify a selection by passing in a comma-separated list of Single Send IDs as the value of the query string parameter `singlesend_ids`. + + Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. + + You can retrieve a specific page of responses with the `page_token` query string parameter. + parameters: + - name: singlesend_ids + in: query + description: This endpoint returns all Single Send IDs if no IDs are included in `singlesend_ids`. + type: array + minItems: 1 + maxItems: 25 + items: + type: string + - $ref: '#/parameters/trait:pagination:page_size' + - $ref: '#/parameters/trait:pagination:page_token' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/singlesends-response' + '400': + $ref: '#/responses/trait:errorResponse:400' + security: + - Authorization: [] + '/marketing/stats/singlesends/{id}': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: get-singlesend-stat + summary: Get Single Send Stats by ID + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint allows you to retrieve stats for an individual Single Send using a Single Send ID.** + + Multiple Single Send IDs can be retrieved using the #endpoint:CkrCH9JrWPiySTTuu endpoint. Once you have an ID, this endpoint will return detailed stats for the Single Send specified. + + You may constrain the stats returned using the `start_date` and `end_date` query string parameters. You can also use the `group_by` and `aggregated_by` query string parameters to further refine the stats returned. + parameters: + - $ref: '#/parameters/trait:baseParams:aggregated_by' + - $ref: '#/parameters/trait:baseParams:start_date' + - $ref: '#/parameters/trait:baseParams:end_date' + - $ref: '#/parameters/trait:baseParams:timezone' + - $ref: '#/parameters/trait:pagination:page_size' + - $ref: '#/parameters/trait:pagination:page_token' + - $ref: '#/parameters/trait:singlesendQueryParams:group_by' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/singlesends-response' + '400': + $ref: '#/responses/trait:errorResponse:400' + '404': + description: '' + security: + - Authorization: [] + '/marketing/stats/automations/{id}/links': + parameters: + - name: id + in: path + description: 'The ID of the Automation you want to get click tracking stats for. ' + required: true + type: string + format: uuid + get: + operationId: get-automation-link-stat + summary: Get Automation Click Tracking Stats by ID + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint lets you retrieve click-tracking stats for a single Automation**. + + The stats returned list the URLs embedded in your Automation and the number of clicks each one received. + + Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. + + You can retrieve a specific page of responses with the `page_token` query string parameter. + parameters: + - $ref: '#/parameters/trait:automationQueryParams:group_by' + - $ref: '#/parameters/trait:automationQueryParams:step_ids' + - $ref: '#/parameters/trait:pagination:page_size' + - $ref: '#/parameters/trait:pagination:page_token' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/automations-link-stats-response' + '400': + $ref: '#/responses/trait:errorResponse:400' + '404': + description: '' + security: + - Authorization: [] + '/marketing/stats/singlesends/{id}/links': + parameters: + - name: id + in: path + required: true + type: string + get: + operationId: get-singlesend-link-stat + summary: Get Single Send Click Tracking Stats by ID + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint lets you retrieve click-tracking stats for one Single Send**. + + The stats returned list the URLs embedded in the specified Single Send and the number of clicks each one received. + + Responses are paginated. You can limit the number of responses returned per batch using the `page_size` query string parameter. The default is 50, but you specify a value between 1 and 100. + + You can retrieve a specific page of responses with the `page_token` query string parameter. + parameters: + - $ref: '#/parameters/trait:pagination:page_size' + - $ref: '#/parameters/trait:pagination:page_token' + - $ref: '#/parameters/trait:singlesendQueryParams2:group_by' + - $ref: '#/parameters/trait:singlesendQueryParams2:ab_variation_id' + - $ref: '#/parameters/trait:singlesendQueryParams2:ab_phase_id' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/singlesends-link-stats-response' + '400': + $ref: '#/responses/trait:errorResponse:400' + '404': + description: '' + schema: + type: object + security: + - Authorization: [] + /marketing/stats/singlesends/export: + get: + operationId: get-singlesend-stats-export + summary: Export Single Send Stats + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint allows you to export Single Send stats as .CSV data**. + + You can specify one Single Send or many: include as many Single Send IDs as you need, separating them with commas, as the value of the `ids` query string paramter. + + The data is returned as plain text response but in .CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a .csv file. + parameters: + - name: ids + in: query + description: The IDs of Single Sends for which to export stats. + type: array + minItems: 1 + maxItems: 50 + items: + type: string + - name: timezone + in: query + description: 'The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented; i.e. `"America/Chicago"`. This parameter changes the timezone format only; it does not alter which stats are returned.' + type: string + default: UTC + responses: + '200': + description: '' + schema: + type: string + description: CSV data + '400': + description: '' + security: + - Authorization: [] + /marketing/stats/automations/export: + get: + operationId: get-automations-stats-export + summary: Export Automation Stats + tags: + - Marketing Campaigns Stats + description: |- + **This endpoint allows you to export Automation stats as CSV data**. + + You can specify one Automation or many: include as many Automation IDs as you need, separating them with commas, as the value of the `ids` query string paramter. + + The data is returned as plain text response but in CSV format, so your application making the call can present the information in whatever way is most appropriate, or just save the data as a `.csv` file. + parameters: + - name: ids + in: query + description: The IDs of Automations for which to export stats. + type: array + minItems: 1 + maxItems: 50 + items: + type: string + - name: timezone + in: query + description: 'The [IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented; i.e. `"America/Chicago"`. This parameter changes the timezone format only; it does not alter which stats are returned.' + type: string + default: UTC + responses: + '200': + description: '' + schema: + type: string + description: CSV data + '400': + description: '' + security: + - Authorization: [] + /senders: + post: + operationId: POST_senders + summary: Create a Sender Identity + tags: + - Sender Identities API + description: |- + **This endpoint allows you to create a new sender identity.** + + *You may create up to 100 unique sender identities.* + + Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`. + parameters: + - name: body + in: body + schema: + type: object + properties: + nickname: + type: string + description: A nickname for the sender identity. Not used for sending. + from: + type: object + properties: + email: + type: string + description: This is where the email will appear to originate from for your recipient + name: + type: string + description: This is the name appended to the from email field. IE - Your name or company name. + required: + - email + reply_to: + type: object + properties: + email: + type: string + description: This is the email that your recipient will reply to. + name: + type: string + description: This is the name appended to the reply to email field. IE - Your name or company name. + required: + - email + address: + type: string + description: The physical address of the sender identity. + address_2: + type: string + description: Additional sender identity address information. + city: + type: string + description: The city of the sender identity. + state: + type: string + description: The state of the sender identity. + zip: + type: string + description: The zipcode of the sender identity. + country: + type: string + description: The country of the sender identity. + required: + - nickname + - address + - city + - country + example: + nickname: My Sender ID + from: + email: from@example.com + name: Example INC + reply_to: + email: replyto@example.com + name: Example INC + address: 123 Elm St. + address_2: Apt. 456 + city: Denver + state: Colorado + zip: '80202' + country: United States + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': + description: '' + schema: + $ref: '#/definitions/senderID' + examples: + application/json: + id: 1 + nickname: My Sender ID + from: + email: from@example.com + name: Example INC + reply_to: + email: replyto@example.com + name: Example INC + address: 123 Elm St. + address_2: Apt. 456 + city: Denver + state: Colorado + zip: '80202' + country: United States + verified: true + updated_at: 1449872165 + created_at: 1449872165 + locked: false + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: The JSON you have submitted cannot be parsed. + field: '' + - message: You've reached your limit of 100 sender identities. Please delete one or more and try again. + field: '' + - message: nickname is required. + field: nickname + - message: You already have a sender identity with the same nickname. + field: nickname + - message: from_name is required. + field: from_name + - message: from_email is required. + field: from_email + - message: From email is not a valid email address. + field: from_email + - message: reply_to is required. + field: reply_to + - message: Reply to email is not a valid email address. + field: reply_to + - message: address is required. + field: address + - message: city is required. + field: city + - message: country is required. + field: country + security: + - Authorization: [] + get: + operationId: GET_v3-senders + summary: Get all Sender Identities + tags: + - Sender Identities API + description: |- + **This endpoint allows you to retrieve a list of all sender identities that have been created for your account.** + + Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/senderID' + examples: + application/json: + result: + - id: 1 + nickname: My Sender ID + from: + email: from@example.com + name: Example INC + reply_to: + email: replyto@example.com + name: Example INC + address: 123 Elm St. + address_2: Apt. 456 + city: Denver + state: Colorado + zip: '80202' + country: United States + verified: true + updated_at: 1449872165 + created_at: 1449872165 + locked: false + security: + - Authorization: [] + '/senders/{sender_id}': + parameters: + - name: sender_id + in: path + description: The ID of the sender identity that you want to update. + required: true + type: integer + patch: + operationId: PATCH_v3-senders-sender_id + summary: Update a Sender Identity + tags: + - Sender Identities API + description: |- + **This endpoint allows you to update a sender identity.** + + Updates to `from.email` require re-verification. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`. + + Partial updates are allowed, but fields that are marked as "required" in the POST (create) endpoint must not be nil if that field is included in the PATCH request. + parameters: + - name: body + in: body + schema: + type: object + properties: + nickname: + type: string + description: A nickname for the sender identity. Not used for sending. + from: + type: object + properties: + email: + type: string + description: This is where the email will appear to originate from for your recipient + name: + type: string + description: This is the name appended to the from email field. IE - Your name or company name. + reply_to: + type: object + properties: + email: + type: string + description: This is the email that your recipient will reply to. + name: + type: string + description: This is the name appended to the reply to email field. IE - Your name or company name. + address: + type: string + description: The physical address of the sender identity. + address_2: + type: string + description: Additional sender identity address information. + city: + type: string + description: The city of the sender identity. + state: + type: string + description: The state of the sender identity. + zip: + type: string + description: The zipcode of the sender identity. + country: + type: string + description: The country of the sender identity. + example: + nickname: My Sender ID + from: + email: from@example.com + name: Example INC + reply_to: + email: replyto@example.com + name: Example INC + address: 123 Elm St. + address_2: Apt. 456 + city: Denver + state: Colorado + zip: '80202' + country: United States + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/senderID' + examples: + application/json: + id: 1 + nickname: My Sender ID + from: + email: from@example.com + name: Example INC + reply_to: + email: replyto@example.com + name: Example INC + address: 123 Elm St. + address_2: Apt. 456 + city: Denver + state: Colorado + zip: '80202' + country: United States + verified: true + updated_at: 1449872165 + created_at: 1449872165 + locked: false + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: The JSON you have submitted cannot be parsed. + field: '' + - message: nickname is required. + field: nickname + - message: You already have a sender identity with the same nickname. + field: nickname + - message: from_name is required. + field: from_name + - message: from_email is required. + field: from_email + - message: From email is not a valid email address. + field: from_email + - message: reply_to is required. + field: reply_to + - message: Reply to email is not a valid email address. + field: reply_to + - message: address is required. + field: address + - message: city is required. + field: city + - message: country is required. + field: country + '403': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: You may only update a sender identity when it is unlocked. + field: locked + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: resource not found + field: id + security: + - Authorization: [] + delete: + operationId: DELETE_v3-senders-sender_id + summary: Delete a Sender Identity + tags: + - Sender Identities API + description: |- + **This endoint allows you to delete one of your sender identities.** + + Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + properties: {} + '403': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: You may only delete a sender identity when it is unlocked. + field: locked + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: resource not found + field: id + security: + - Authorization: [] + get: + operationId: GET_v3-senders-sender_id + summary: View a Sender Identity + tags: + - Sender Identities API + description: |- + **This endpoint allows you to retrieve a specific sender identity.** + + Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/senderID' + examples: + application/json: + id: 1 + nickname: My Sender ID + from: + email: from@example.com + name: Example INC + reply_to: + email: replyto@example.com + name: Example INC + address: 123 Elm St. + address_2: Apt. 456 + city: Denver + state: Colorado + zip: '80202' + country: United States + verified: true + updated_at: 1449872165 + created_at: 1449872165 + locked: false + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: resource not found + field: id + security: + - Authorization: [] + '/senders/{sender_id}/resend_verification': + parameters: + - name: sender_id + in: path + description: The ID of the sender identity for which you would like to resend a verification email. + required: true + type: integer + post: + operationId: POST_v3-senders-sender_id-resend_verification + summary: Resend Sender Identity Verification + tags: + - Sender Identities API + description: |- + **This enpdoint allows you to resend a sender identity verification email.** + + Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise an email will be sent to the `from.email`. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + properties: {} + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: The Sender Identity is already verified. No email sent. + field: '' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: resource not found + field: id + security: + - Authorization: [] + /contactdb/lists: + post: + operationId: POST_contactdb-lists + summary: Create a List + tags: + - Contacts API - Lists + description: '**This endpoint allows you to create a list for your recipients.**' + parameters: + - name: body + in: body + schema: + title: Create a List request + type: object + properties: + name: + type: string + required: + - name + example: + name: your list name + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + get: + operationId: GET_contactdb-lists + summary: Retrieve all lists + tags: + - Contacts API - Lists + description: '**This endpoint allows you to retrieve all of your recipient lists. If you don''t have any lists, an empty array will be returned.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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 + security: + - Authorization: [] + delete: + operationId: DELETE_contactdb-lists + summary: Delete Multiple lists + tags: + - Contacts API - Lists + description: '**This endpoint allows you to delete multiple recipient lists.**' + parameters: + - name: body + in: body + schema: + type: array + items: + type: integer + example: + - 1 + - 2 + - 3 + - 4 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: 'null' + '400': + description: '"id" : "Returned if all list ids are not valid"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: list id was invalid + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + '/contactdb/lists/{list_id}': + parameters: + - name: list_id + in: path + required: true + type: string + get: + operationId: GET_contactdb-lists-list_id + summary: Retrieve a single list + tags: + - Contacts API - Lists + description: '**This endpoint allows you to retrieve a single recipient list.**' + parameters: + - name: list_id + in: query + description: The ID of the list to retrieve. + type: integer + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + examples: + application/json: + errors: + - message: invalid id + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"list_id" : "Returned if list_id does not exist"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: List ID does not exist + security: + - Authorization: [] + patch: + operationId: PATCH_contactdb-lists-list_id + summary: Update a List + tags: + - Contacts API - Lists + description: '**This endpoint allows you to update the name of one of your recipient lists.**' + parameters: + - name: list_id + in: query + description: The ID of the list you are updating. + required: true + type: integer + - 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 + example: + name: newlistname + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + id: + type: integer + description: The ID of the list + name: + type: string + description: The new name for the list + recipient_count: + type: integer + description: The number of recipients on the list + examples: + application/json: + id: 1234 + name: 2016 iPhone Users + recipient_count: 0 + '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_error_response_schema' + examples: + application/json: + errors: + - message: invalid id + '404': + description: '"list_id" : "Returned if list_id does not exist"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - message: List ID does not exist + security: + - Authorization: [] + delete: + operationId: DELETE_contactdb-lists-list_id + summary: Delete a List + tags: + - Contacts API - Lists + description: '**This endpoint allows you to delete a specific recipient list with the given ID.**' + 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 + - name: body + in: body + schema: + type: 'null' + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"list_id" : "Returned if list_id does not exist"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - message: 'List not found: 5' + security: + - Authorization: [] + '/contactdb/lists/{list_id}/recipients': + parameters: + - name: list_id + in: path + description: The id of the list of recipients you want to retrieve. + required: true + type: integer + get: + operationId: GET_contactdb-lists-list_id-recipients + summary: Retrieve all recipients on a List + tags: + - Contacts API - Lists + description: '**This endpoint allows you to retrieve all recipients on the list with the given ID.**' + parameters: + - name: page + in: query + description: Page index of first recipient to return (must be a positive integer) + required: false + type: integer + - name: page_size + in: query + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) + required: false + type: integer + - name: list_id + in: query + description: The ID of the list whose recipients you are requesting. + required: true + type: integer + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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" + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" + schema: + $ref: '#/definitions/global_error_response_schema' + 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 + examples: + application/json: + errors: + - field: list_id + message: Returned if list_id is invalid + security: + - Authorization: [] + post: + operationId: POST_contactdb-lists-list_id-recipients + summary: Add Multiple Recipients to a List + tags: + - Contacts API - Lists + description: |- + **This endpoint allows you to add multiple recipients to a list.** + + Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. + parameters: + - name: body + in: body + schema: + type: array + items: + type: string + example: + - recipient_id1 + - recipient_id2 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': + description: '' + schema: + type: 'null' + '400': + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "" : "Returned if no valid recipient ids were passed" + "" : "Returned if no recipients were added" + "" : "Returned if request body is invalid JSON" + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"list_id": "Returned if list_id does not exist"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: list_id + message: list_id does not exist + - field: recipient_id + message: recipient_id does not exist + security: + - Authorization: [] + '/contactdb/lists/{list_id}/recipients/{recipient_id}': + parameters: + - name: list_id + in: path + description: The ID of the list that you want to add the recipient to. + required: true + type: integer + - name: recipient_id + in: path + description: The ID of the recipient you are adding to the list. + required: true + type: string + post: + operationId: POST_contactdb-lists-list_id-recipients-recipient_id + summary: Add a Single Recipient to a List + tags: + - Contacts API - Lists + description: '**This endpoint allows you to add a single recipient to a list.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + 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 + security: + - Authorization: [] + delete: + operationId: DELETE_contactdb-lists-list_id-recipients-recipient_id + summary: Delete a Single Recipient from a Single List + tags: + - Contacts API - Lists + description: '**This endpoint allows you to delete a single recipient from a list.**' + parameters: + - name: list_id + in: query + description: The ID of the list you are taking this recipient away from. + required: true + type: integer + - name: recipient_id + in: query + description: The ID of the recipient to take off the list. + required: true + type: integer + - name: body + in: body + schema: + type: 'null' + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + 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_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + 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 + security: + - Authorization: [] + /contactdb/recipients: + post: + operationId: POST_contactdb-recipients + summary: Add recipients + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to add a Marketing Campaigns recipient.** + + 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 rate limit is three requests every 2 seconds. You can upload 1000 contacts per request. So the maximum upload rate is 1500 recipients per second. + parameters: + - name: body + in: body + schema: + type: array + items: + type: object + properties: + email: + type: string + description: The email address of the recipient. + format: email + first_name: + type: string + description: The first name of the recipient. + last_name: + type: string + description: The last name of the recipient. + age: + type: integer + required: + - email + example: + - email: example@example.com + first_name: '' + last_name: User + age: 25 + - email: example2@example.com + first_name: Example + last_name: User + age: 25 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: Request body is not valid json + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + patch: + operationId: PATCH_contactdb-recipients + summary: Update Recipient + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to update one or more recipients.** + + The body of an API call to this endpoint must include an array of one or more recipient objects. + + 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. + parameters: + - name: body + in: body + 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. + required: + - email + example: + - email: jones@example.com + last_name: Jones + first_name: Guy + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': + description: '' + schema: + $ref: '#/definitions/contactdb_recipient_response' + '400': + description: '"" : "Returned if request body is not valid json"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: Request body is not valid json + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + delete: + operationId: DELETE_contactdb-recipients + summary: Delete Recipients + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to deletes one or more recipients.** + + The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. + parameters: + - name: body + in: body + schema: + type: array + items: + type: string + example: + - recipient_id1 + - recipient_id2 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + '400': + description: |- + "" : "Returned if no recipients are deleted" + "" : "Returned if all of the provided recipient ids are invalid" + "" : "Returned if request body is not valid json" + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - message: No recipient ids provided + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + get: + operationId: GET_contactdb-recipients + summary: Retrieve recipients + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** + + Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of + the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. + 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 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + title: List Recipients response + type: object + properties: + recipients: + type: array + items: + type: object + required: + - recipients + '400': + description: |- + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" + schema: + type: object + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + /contactdb/status: + get: + operationId: GET_contactdb-status + summary: Get Recipient Upload Status + tags: + - Contacts API - Recipients + description: '**This endpoint allows you to check the upload status of a Marketing Campaigns recipient.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + status: + type: array + items: + type: object + properties: + id: + type: string + default: '' + description: Valid values are "worker_delay" and "worker_delay_seconds" (the second value appears only if "worker_delay" has a value of "delayed"). + value: + type: string + default: '' + description: Valid values for the ID "worker_delay" are "OK" or "Delayed". Valid values for the ID "worker_delay_seconds" is the time of delay to upload. + '': + type: string + examples: + application/json: + status: + - id: worker_delay + value: delayed + - id: worker_delay_seconds + value: '75.0' + security: + - Authorization: [] + '/contactdb/recipients/{recipient_id}': + parameters: + - name: recipient_id + in: path + description: The ID of the recipient that you want to retrieve. + required: true + type: string + get: + operationId: GET_contactdb-recipients-recipient_id + summary: Retrieve a single recipient + tags: + - Contacts API - Recipients + description: '**This endpoint allows you to retrieve a single recipient by ID from your contact database.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contactdb_recipient' + '400': + description: '"recipient_id" : "Returned if recipient_id is not valid"' + schema: + type: object + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"recipient_id" : "Returned if record for recipient id does not exist"' + schema: + type: object + security: + - Authorization: [] + delete: + operationId: DELETE_contactdb-recipients-recipient_id + summary: Delete a Recipient + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to delete a single recipient with the given ID from your contact database.** + + > Use this to permanently delete your recipients from all of your contact lists and all segments if required by applicable law. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + '400': + description: '"recipient_id" : "Returned if recipient_id is not valid"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: recipient not found + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: recipient_id is not valid + security: + - Authorization: [] + '/contactdb/recipients/{recipient_id}/lists': + parameters: + - name: recipient_id + in: path + description: The ID of the recipient for whom you are retrieving lists. + required: true + type: string + get: + operationId: GET_contactdb-recipients-recipient_id-lists + summary: Retrieve the lists that a recipient is on + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to retrieve the lists that a given recipient belongs to.** + + Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: recipient ID is invalid + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: recipient id not found + security: + - Authorization: [] + /contactdb/recipients/billable_count: + get: + operationId: GET_contactdb-recipients-billable_count + summary: Retrieve the count of billable recipients + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.** + + You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contactdb_recipient_count' + examples: + application/json: + recipient_count: 1234 + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + /contactdb/recipients/count: + get: + operationId: GET_contactdb-recipients-count + summary: Retrieve a Count of Recipients + tags: + - Contacts API - Recipients + description: '**This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/contactdb_recipient_count' + examples: + application/json: + recipient_count: 1234 + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + /contactdb/recipients/search: + get: + operationId: GET_contactdb-recipients-search + summary: Search recipients + tags: + - Contacts API - Recipients + description: |- + **This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** + + 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. + parameters: + - name: '{field_name}' + in: query + type: string + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + recipients: + type: array + items: + $ref: '#/definitions/contactdb_recipient' + examples: + application/json: + recipients: + - created_at: 1422313607 + email: jones@example.com + first_name: null + id: YUBh + last_clicked: null + last_emailed: null + last_name: Jones + last_opened: null + updated_at: 1422313790 + custom_fields: + - id: 23 + name: pet + value: Fluffy + type: text + '400': + description: |- + "" : "Returned if no search params are specified" + "field" : "Returned if the provided field is invalid or does not exist" + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + post: + operationId: POST_contactdb-recipients-search + summary: Search recipients + tags: + - Contacts API - Recipients + description: |- +

+ Search using segment conditions without actually creating a segment. + Body contains a JSON object with conditions, a list of conditions as described below, and an optional list_id, which is a valid list ID for a list to limit the search on. +

+ +

+ Valid operators for create and update depend on the type of the field for which you are searching. +

+ +
    +
  • Dates: +
      +
    • "eq", "ne", "lt" (before), "gt" (after) +
        +
      • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
        • +
      +
      • +
    • "empty", "not_empty"
      • +
    • "is within" + +
      • +
    +
    • +
  • Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value), "empty", "not_empty"
    • +
  • Numbers: "eq", "lt", "gt", "empty", "not_empty"
    • +
  • Email Clicks and Opens: "eq" (opened), "ne" (not opened)
    • +
+ +

+ Field values must all be a string. +

+ +

+ Search 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. +

+ +

+ Search conditions list may contain multiple conditions, 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". +

+ parameters: + - name: body + in: body + schema: + type: object + properties: + list_id: + type: integer + format: int32 + conditions: + type: array + items: + and_or: '' + field: birthday + value: 01/12/1985 + operator: eq + required: + - list_id + - conditions + example: + list_id: -27497588 + conditions: + - and_or: '' + field: birthday + value: 01/12/1985 + operator: eq + - and_or: '' + field: birthday + value: 01/12/1985 + operator: eq + - and_or: '' + field: birthday + value: 01/12/1985 + operator: eq + - and_or: '' + field: birthday + value: 01/12/1985 + operator: eq + responses: + '200': + description: '' + schema: + type: object + properties: + recipients: + type: array + items: + type: object + properties: + created_at: + type: integer + email: + type: string + id: + type: string + last_emailed: + type: integer + last_clicked: + type: integer + last_opened: + type: integer + custom_fields: + type: array + items: + type: object + properties: + id: + type: integer + name: + type: string + value: + anyOf: + - type: integer + - type: string + type: + type: string + updated_at: + type: integer + first_name: + type: string + recipient_count: + type: integer + examples: + application/json: + recipients: + - created_at: -27901208 + email: ut magna quis ipsum + id: fugiat ad adipisicing ullamco + last_emailed: 21626657 + - created_at: 17466400 + email: sunt irure + id: et + last_clicked: -23135244 + last_opened: -44593357 + first_name: est + - created_at: -34495329 + email: reprehenderit incididunt velit Lorem esse + id: esse Ut ad dolore + last_clicked: 10164083 + last_opened: 34443062 + - created_at: -37030673 + email: amet deserunt fugiat voluptate + id: et exercitation commodo id laborum + last_clicked: -10497425 + - created_at: 3658435 + email: labore veniam + id: ad pariatur esse + last_opened: -84227501 + custom_fields: + - id: -5765608 + name: proident pariatur + value: do in magna mollit + type: dolore ut + - id: -31131201 + name: laborum mollit + value: 84434696 + type: veniam + updated_at: -56455352 + first_name: Ut cupidatat nulla deserunt adipisicing + last_clicked: -52862671 + recipient_count: 65190677 + '400': + description: '' + security: + - Authorization: [] + /contactdb/custom_fields: + post: + operationId: POST_contactdb-custom_fields + summary: Create a Custom Field + tags: + - Contacts API - Custom Fields + description: |- + **This endpoint allows you to create a custom field.** + + **You can create up to 120 custom fields.** + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + type: + type: string + example: + name: pet + type: text + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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" + "type" : "Returned if custom field type is invalid or not provided" + "name" : "Returned if custom field name is not provided" + schema: + $ref: '#/definitions/error_schema' + 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 + security: + - Authorization: [] + get: + operationId: GET_contactdb-custom_fields + summary: Retrieve all custom fields + tags: + - Contacts API - Custom Fields + description: '**This endpoint allows you to retrieve all custom fields.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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: + custom_fields: + - id: 6234 + name: age + type: number + - id: 6233 + name: country + type: text + - id: 6235 + name: favorite_color + type: text + - id: 6239 + name: fname + type: text + - id: 6240 + name: lname + type: text + - id: 49439 + name: pet + type: text + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + '/contactdb/custom_fields/{custom_field_id}': + parameters: + - name: custom_field_id + in: path + description: The ID of the custom field that you want to retrieve. + required: true + type: integer + get: + operationId: GET_contactdb-custom_fields-custom_field_id + summary: Retrieve a Custom Field + tags: + - Contacts API - Custom Fields + description: '**This endpoint allows you to retrieve a custom field by ID.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + examples: + application/json: + errors: + - message: invalid id + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - message: Custom field ID does not exist + security: + - Authorization: [] + delete: + operationId: DELETE_contactdb-custom_fields-custom_field_id + summary: Delete a Custom Field + tags: + - Contacts API - Custom Fields + description: '**This endpoint allows you to delete a custom field by ID.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '202': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + message: Custom Field delete is processing. + '400': + description: '"id" : "Returned if custom_field_id is not valid"' + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - message: Custom field ID does not exist + security: + - Authorization: [] + /contactdb/reserved_fields: + get: + operationId: GET_contactdb-reserved_fields + summary: Retrieve reserved fields + tags: + - Contacts API - Custom Fields + description: '**This endpoint allows you to list all fields that are reserved and can''t be used for custom field names.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + reserved_fields: + type: array + items: + type: object + properties: + name: + type: string + type: + type: string + 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: lists + type: set + - name: campaigns + type: set + - name: my_custom_field + type: text + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + /contactdb/segments: + post: + operationId: POST_contactdb-segments + summary: Create a Segment + tags: + - Contacts API - Segments + description: |- +

+ Create a segment using search conditions. + Body contains a JSON object with conditions, a list of conditions as described below, a unique name, and an optional list_id, which is a valid list ID for a list to limit the search on. +

+ +

+ Valid operators for create and update depend on the type of the field for which you are searching. +

+ +
    +
  • Dates: +
      +
    • "eq", "ne", "lt" (before), "gt" (after) +
        +
      • You may use MM/DD/YYYY for day granularity or an epoch for second granularity.
        • +
      +
      • +
    • "empty", "not_empty"
      • +
    • "is within" + +
      • +
    +
    • +
  • Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value), "empty", "not_empty"
    • +
  • Numbers: "eq", "lt", "gt", "empty", "not_empty"
    • +
  • Email Clicks and Opens: "eq" (opened), "ne" (not opened)
    • +
+ +

+ Field values must all be a string. +

+ +

+ 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. +

+ +

+ The conditions list may contain multiple conditions, 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". +

+ parameters: + - name: body + in: body + schema: + $ref: '#/definitions/contactdb_segments' + example: + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + - field: last_clicked + value: 01/02/2015 + operator: gt + and_or: and + - field: clicks.campaign_identifier + value: '513' + operator: eq + and_or: or + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + get: + operationId: GET_contactdb-segments + summary: Retrieve all segments + tags: + - Contacts API - Segments + description: '**This endpoint allows you to retrieve all of your segments.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + '/contactdb/segments/{segment_id}': + parameters: + - name: segment_id + in: path + required: true + type: string + get: + operationId: GET_contactdb-segments-segment_id + summary: Retrieve a segment + tags: + - Contacts API - Segments + description: '**This endpoint allows you to retrieve a single segment with the given ID.**' + parameters: + - name: segment_id + in: query + description: The ID of the segment you want to request. + required: true + type: integer + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + examples: + application/json: + errors: + - message: if segment_id is not valid + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"segment_id" : "Returned if segment_id does not exist"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - message: segment_id not found + security: + - Authorization: [] + patch: + operationId: PATCH_contactdb-segments-segment_id + summary: Update a segment + tags: + - Contacts API - Segments + description: '**This endpoint allows you to update a segment.**' + 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 + example: + name: The Millers + list_id: 5 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + delete: + operationId: DELETE_contactdb-segments-segment_id + summary: Delete a segment + tags: + - Contacts API - Segments + description: |- + **This endpoint allows you to delete a segment from your recipients database.** + + You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. + parameters: + - name: delete_contacts + in: query + description: True to delete all contacts matching the segment in addition to deleting the segment + type: boolean + - name: body + in: body + schema: + type: 'null' + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: 'null' + '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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"segment_id" : "Returned if segment_id does not exist"' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: segment_id + message: segment_id does not exist + security: + - Authorization: [] + '/contactdb/segments/{segment_id}/recipients': + parameters: + - name: segment_id + in: path + description: The ID of the segment from which you want to retrieve recipients. + required: true + type: integer + get: + operationId: GET_contactdb-segments-segment_id-recipients + summary: Retrieve recipients on a segment + tags: + - Contacts API - Segments + description: '**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**' + parameters: + - name: page + in: query + type: integer + - name: page_size + in: query + type: integer + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + schema: + type: object + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: |- + "segment_id" : "Returned if segment_id is not valid" + "segment_id" : "Returned if segment_id does not exist" + schema: + type: object + security: + - Authorization: [] + /categories: + get: + operationId: GET_categories + summary: Retrieve all categories + tags: + - Categories + description: |- + **This endpoint allows you to retrieve a list of all of your categories.** + + Categories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories. + parameters: + - name: limit + in: query + description: The number of categories to display per page. + type: integer + default: 50 + - name: category + in: query + description: Allows you to perform a prefix search on this particular category. + type: string + - name: offset + in: query + description: The point in the list that you would like to begin displaying results. + type: integer + default: 0 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: array + items: + type: object + properties: + category: + type: string + description: A category used to group emails by broad topic. + required: + - category + examples: + application/json: + - category: category 1 + - category: category 2 + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + description: The error returned. + items: + type: object + properties: + field: + type: string + message: + type: string + description: A message explaining why your categories could not be retrieved. + required: + - field + - message + examples: + application/json: + errors: + - field: sort_by + message: invalid sort value + security: + - Authorization: [] + /categories/stats/sums: + get: + operationId: GET_categories-stats-sums + summary: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' + tags: + - Categories + description: |- + **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.** + + If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. + + Categories allow you to group your emails together according to broad topics that you define. + + > Category statistics are available for the previous thirteen months only. + parameters: + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string + default: delivered + - name: sort_by_direction + in: query + description: The direction you want to sort. + required: false + type: string + default: desc + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: limit + in: query + description: Limits the number of results returned. + required: false + type: integer + default: 5 + - name: offset + in: query + description: The point in the list to begin retrieving results. + required: false + type: integer + default: 0 + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/category_stats' + examples: + application/json: + date: '2015-01-01' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 20 + deferred: 0 + delivered: 20 + invalid_emails: 0 + opens: 20 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 20 + unique_opens: 20 + unsubscribe_drops: 0 + unsubscribes: 20 + name: cat1 + type: category + - metrics: + blocks: 1 + bounce_drops: 0 + bounces: 0 + clicks: 19 + deferred: 0 + delivered: 19 + invalid_emails: 0 + opens: 19 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 19 + unique_opens: 19 + unsubscribe_drops: 0 + unsubscribes: 19 + name: cat2 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 5 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 5 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 5 + name: cat3 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 6 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 6 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 6 + name: cat4 + type: category + - metrics: + blocks: 10 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 10 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: cat5 + type: category + security: + - Authorization: [] + /categories/stats: + get: + operationId: GET_categories-stats + summary: Retrieve Email Statistics for Categories + tags: + - Categories + description: |- + **This endpoint allows you to retrieve all of your email statistics for each of your categories.** + + If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. + + Categories allow you to group your emails together according to broad topics that you define. + + > Category statistics are available for the previous thirteen months only. + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: categories + in: query + description: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. + required: true + type: string + - name: limit + in: query + description: The number of results to include. + required: false + type: integer + default: 500 + maximum: 500 + - name: offset + in: query + description: The number of results to skip. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/category_stats' + examples: + application/json: + - date: '2015-10-01' stats: - - type: mailbox_provider - name: Gmail + - type: category + name: docs metrics: blocks: 0 + bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - drops: 0 + invalid_emails: 0 opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 - - date: '2015-10-31' - stats: - - type: mailbox_provider - name: Gmail + unsubscribe_drops: 0 + unsubscribes: 0 + - type: category + name: mattscategory metrics: blocks: 0 + bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - drops: 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: 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 + - type: category + name: docs metrics: blocks: 0 + bounce_drops: 0 bounces: 0 clicks: 0 deferred: 0 delivered: 0 - drops: 0 + invalid_emails: 0 opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-11-10' - stats: - - type: mailbox_provider - name: Gmail + 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 - drops: 0 + invalid_emails: 0 opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 spam_reports: 0 unique_clicks: 0 unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + security: + - Authorization: [] + /campaigns: + post: + operationId: POST_campaigns + summary: Create a Campaign + tags: + - Campaigns API + description: |- + **This endpoint allows you to create a campaign.** + + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + + Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/campaign_request' + example: + title: March Newsletter + subject: New Products for Spring! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:

Check out our spring line!

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

Check out our spring line!

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

Check out our spring line!

+ id: 986724 + ip_pool: marketing + list_ids: + - 110 + plain_content: Check out our spring line! + segment_ids: + - 110 + sender_id: 124451 + status: Draft + subject: New Products for Spring! + suppression_group_id: 42 + title: March Newsletter + '401': + description: '' + schema: + type: object + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"": "not found"' + schema: + type: object + examples: + application/json: + errors: + - field: null + message: not found + security: + - Authorization: [] + delete: + operationId: DELETE_campaigns-campaign_id + summary: Delete a Campaign + tags: + - Campaigns API + description: |- + **This endpoint allows you to delete a specific campaign.** + + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: 'null' + '401': + description: '' + schema: + type: object + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"": "not found"' + schema: + type: object + security: + - Authorization: [] + patch: + operationId: PATCH_campaigns-campaign_id + summary: Update a Campaign + tags: + - Campaigns API + 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.' + 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 + 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! + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/campaign_response' + examples: + application/json: + id: 986724 + title: May Newsletter + subject: New Products for Summer! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - summer line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:

Check out our summer line!

+ plain_content: Check out our summer line! + status: Draft + '400': + description: |- + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." + schema: + type: object + examples: + application/json: + errors: + - field: title + message: title can't be blank + - field: title + message: title is too long (maximum is 100 characters) + - field: categories + message: categories exceeds 10 category limit + - field: html_content + message: html_content exceeds the 1MB limit + - field: plain_content + message: plain_content exceeds the 1MB limit + - field: sender_id + message: sender_id does not exist + - field: sender_id + message: sender_id is not a verified sender identity + - field: list_ids + message: list_ids do not all exist + - field: segment_ids + message: segment_ids do not all exist + - field: ip_pool + message: The ip pool you provided is invalid + - field: suppression_group_id + message: suppression_group_id does not exist + - field: unsubscribes + message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' + - field: null + message: The JSON you have submitted cannot be parsed. + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 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 + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: not found + security: + - Authorization: [] + '/campaigns/{campaign_id}/schedules/now': + parameters: + - name: campaign_id + in: path + required: true + type: integer + post: + operationId: POST_campaigns-campaign_id-schedules-now + summary: Send a Campaign + tags: + - Campaigns API + description: |- + **This endpoint allows you to immediately send a campaign at the time you make the API call.** + + Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + 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_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: not found security: - Authorization: [] - /browsers/stats: - get: - operationId: GET_browsers-stats - summary: Retrieve email statistics by browser. + '/campaigns/{campaign_id}/schedules': + parameters: + - name: campaign_id + in: path + required: true + type: integer + post: + operationId: POST_campaigns-campaign_id-schedules + summary: Schedule a Campaign tags: - - Stats + - Campaigns API 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. + **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** - 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). - produces: - - application/json + If you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won't be going through our servers at the same times as everyone else's mail. + parameters: + - name: body + in: body + schema: + title: Schedule a Campaign request + type: object + properties: + send_at: + type: integer + description: The unix timestamp for the date and time you would like your campaign to be sent out. + required: + - send_at + example: + send_at: 1489771528 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': + description: '' + schema: + title: Schedule a Campaign response + type: object + properties: + id: + type: integer + description: The campaign ID. + send_at: + type: integer + description: The date time you scheduled your campaign to be sent. + status: + type: string + description: The status of your campaign. + enum: + - Scheduled + required: + - id + - send_at + - status + examples: + application/json: + id: 1234 + send_at: 1489771528 + status: Scheduled + '400': + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "send_at": "Please choose a future time for sending your campaign." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "The JSON you have submitted cannot be parsed." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: not found + security: + - Authorization: [] + patch: + operationId: PATCH_campaigns-campaign_id-schedules + summary: Update a Scheduled Campaign + tags: + - Campaigns API + description: '**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**' + parameters: + - name: body + in: body + schema: + title: Update a Scheduled Campaign request + type: object + properties: + send_at: + type: integer + format: int64 + required: + - send_at + example: + send_at: 1489451436 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + title: Update a Scheduled Campaign response + type: object + properties: + id: + type: integer + description: The campaign ID + send_at: + type: integer + description: The unix timestamp to send the campaign. + status: + type: string + description: The status of the schedule. + required: + - id + - send_at + - status + '400': + description: |- + "": "The JSON you have submitted cannot be parsed." + "send_at": "Please choose a future time for sending your campaign." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + schema: + $ref: '#/definitions/global_error_response_schema' + 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_error_response_schema' + 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_error_response_schema' + examples: + application/json: + errors: + - field: null + message: not found + security: + - Authorization: [] + get: + operationId: GET_campaigns-campaign_id-schedules + summary: View Scheduled Time of a Campaign + tags: + - Campaigns API + description: '**This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.**' 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 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/advanced_stats_clicks' + 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_error_response_schema' 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 + errors: + - field: null + message: not found security: - Authorization: [] - /subusers: - get: - operationId: GET_subusers - summary: List all Subusers + delete: + operationId: DELETE_campaigns-campaign_id-schedules + summary: Unschedule a Scheduled Campaign tags: - - Subusers API + - Campaigns API 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: + **This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.** - * [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) - produces: - - application/json + 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). parameters: - - name: username - in: query - description: The username of this subuser. - type: string - - name: limit - in: query - description: The number of results you would like to get in each request. - type: integer - - name: offset - in: query - description: The number of subusers to skip. - type: integer + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' schema: - type: array - items: - $ref: '#/definitions/subuser' + type: 'null' + '403': + description: |- + "": "This campaign is already In Progress." + "": "This campaign is already Sent." + "": "This campaign is already Paused." + "": "This campaign is already Canceled." + schema: + $ref: '#/definitions/global_error_response_schema' 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. + 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' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - field: null - message: authorization required + message: not found security: - Authorization: [] + '/campaigns/{campaign_id}/schedules/test': + parameters: + - name: campaign_id + in: path + required: true + type: integer post: - operationId: POST_subusers - summary: Create Subuser + operationId: POST_campaigns-campaign_id-schedules-test + summary: Send a Test Campaign tags: - - Subusers API + - Campaigns API 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: + **This endpoint allows you to send a test campaign.** - * [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) - consumes: - - application/json - produces: - - application/json + To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] parameters: - name: body in: body schema: type: object properties: - username: - type: string - description: The username for this subuser. - email: + to: type: string - description: The email address of the subuser. + description: The email address that should receive the test campaign. 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 + - to example: - username: John@example.com - email: John@example.com - password: johns_password - ips: - - 1.1.1.1 - - 2.2.2.2 + to: your.email@example.com + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': 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 + title: Send a Test Campaign request + type: object + properties: + to: + type: string + required: + - to '400': - description: '' + 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/global_error_response_schema' examples: application/json: errors: - - message: username exists - - message: unable to validate IPs at this time - '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 more: https://app.sendgrid.com/settings/billing' + '404': + description: '"": "not found"' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/global_error_response_schema' examples: application/json: errors: - field: null - message: authorization required - '403': + message: not found + security: + - Authorization: [] + /templates: + post: + operationId: POST_templates + summary: Create a transactional template. + tags: + - Transactional Templates + description: '**This endpoint allows you to create a transactional template.**' + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name for the new transactional template. + maxLength: 100 + generation: + type: string + description: Defines whether the template supports dynamic replacement. + enum: + - legacy + - dynamic + default: legacy + required: + - name + example: + name: example_name + generation: dynamic + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '201': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/transactional_template' examples: application/json: - errors: - - message: you dont have permission to access this resource - '500': + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: example_name + generation: legacy + versions: [] + security: + - Authorization: [] + get: + operationId: GET_templates + summary: Retrieve paged transactional templates. + tags: + - Transactional Templates + description: '**This endpoint allows you to retrieve all transactional templates.**' + parameters: + - name: generations + in: query + description: 'Comma-delimited list specifying which generations of templates to return. Options are `legacy`, `dynamic` or `legacy,dynamic`.' + required: false + type: string + default: legacy + enum: + - legacy + - dynamic + - 'legacy,dynamic' + - name: page_size + in: query + description: The number of templates to be returned in each page of results + required: true + type: number + minimum: 1 + maximum: 200 + - name: page_token + in: query + description: 'A token corresponding to a specific page of results, as provided by metadata' + required: false + type: string + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + result: + type: array + description: '' + items: + $ref: '#/definitions/transactional-templates-template-lean' + _metadata: + $ref: '#/definitions/_metadata' + examples: + application/json: + result: + - id: fae7c985-eb92-4b47-9987-28ec29dbc698 + name: example_name + generation: legacy + 'updated_at ': '2020-11-12 12:00:09' + versions: [] + _metadata: + self: 'https://api.sendgrid.com/v3/templates' + count: 1 + '400': description: '' schema: type: object - examples: - application/json: + properties: errors: - - message: unable to validate IPs at this time + type: array + items: + type: object + properties: + '': + type: string + message: + type: string + error_id: + type: string security: - Authorization: [] - '/subusers/{subuser_name}': + '/templates/{template_id}': parameters: - - name: subuser_name + - name: template_id in: path required: true type: string - patch: - operationId: PATCH_subusers-subuser_name - summary: Enable/disable a subuser + post: + operationId: POST_templates-template_id + summary: Duplicate a transactional template. tags: - - Subusers API - 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) - consumes: - - application/json - produces: - - application/json + - Transactional Templates + description: '**This endpoint allows you to duplicate a transactional template.**' 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.' + name: + type: string + description: The name for the new transactional template. + maxLength: 100 example: - disabled: false + name: example_name + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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': + '201': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/transactional_template' examples: application/json: - errors: - - field: null - message: authorization required - '500': + id: 733ba07f-ead1-41fc-933a-3976baa2371 + name: example_name + generation: dynamic + 'updated_at ': '2019-03-13T11:52:41.009Z' + versions: [] + security: + - Authorization: [] + get: + operationId: GET_templates-template_id + summary: Retrieve a single transactional template. + tags: + - Transactional Templates + description: '**This endpoint allows you to retrieve a single transactional template.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/transactional_template' examples: application/json: - errors: - - message: unable to enable user + id: 40da60e6-66f3-4223-9406-ba58b7f55a62 + name: Duis in dolor + generation: legacy + 'updated_at ': '2020-12-12 58:26:65' + versions: [] security: - Authorization: [] - delete: - operationId: DELETE_subusers-subuser_name - summary: Delete a subuser + patch: + operationId: PATCH_templates-template_id + summary: Edit a transactional template. tags: - - Subusers API + - Transactional Templates description: |- - This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. + **This endpoint allows you to edit the name of a transactional template.** - 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) - produces: - - application/json + To edit the template itself, [create a new transactional template version](https://sendgrid.api-docs.io/v3.0/transactional-templates-versions/create-a-new-transactional-template-version). parameters: - name: body in: body - schema: - type: 'null' - responses: - '204': - description: '' schema: type: object - properties: {} - '401': + properties: + name: + type: string + description: The name of the transactional template. + maxLength: 100 + example: + name: new_example_name + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/transactional_template' examples: application/json: - errors: - - field: null - message: authorization required + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: new_example_name + versions: [] security: - Authorization: [] - '/subusers/{subuser_name}/monitor': - parameters: - - name: subuser_name - in: path - description: The name of the subuser for which to retrieve monitor settings. - required: true - type: string - get: - operationId: GET_subusers-subuser_name-monitor - summary: Retrieve monitor settings for a subuser + delete: + operationId: DELETE_templates-template_id + summary: Delete a template. tags: - - Subusers API - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - produces: - - application/json + - Transactional Templates + description: '**This endpoint allows you to delete a transactional template.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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': + '204': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: No monitor settings for this user + type: object security: - Authorization: [] + '/templates/{template_id}/versions': + parameters: + - name: template_id + in: path + required: true + type: string + format: uuid post: - operationId: POST_subusers-subuser_name-monitor - summary: Create monitor settings + operationId: POST_templates-template_id-versions + summary: Create a new transactional template version. tags: - - Subusers API - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - consumes: - - application/json - produces: - - application/json + - Transactional Templates Versions + description: '**This endpoint allows you to create a new version of a template.**' parameters: - name: body in: body schema: - $ref: '#/definitions/monitor' + $ref: '#/definitions/transactional_template_version_create' example: - email: example@example.com - frequency: 50000 + active: 1 + name: example_version_name + html_content: + plain_content: Plain text content + generate_plain_content: false + subject: + editor: design + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/monitor' + $ref: '#/definitions/transactional_template_version_output' examples: application/json: - email: example@example.com - frequency: 50000 - '400': + 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%> + generate_plain_content: true + subject: <%subject%> + updated_at: '2019-03-13 18:56:33' + editor: code + security: + - Authorization: [] + '/templates/{template_id}/versions/{version_id}/activate': + parameters: + - name: template_id + in: path + description: The ID of the original template + required: true + type: string + format: uuid + - name: version_id + in: path + description: The ID of the template version + required: true + type: string + format: uuid + post: + operationId: POST_templates-template_id-versions-version_id-activate + summary: Activate a transactional template version. + tags: + - Transactional Templates Versions + description: '**This endpoint allows you to activate a version of one of your templates.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/transactional_template_version_output' examples: application/json: - errors: - - field: null - message: User already has a monitor - '401': + 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%> + generate_plain_content: true + subject: <%subject%> + updated_at: '2019-03-13 18:56:33' + editor: code + security: + - Authorization: [] + '/templates/{template_id}/versions/{version_id}': + parameters: + - name: template_id + in: path + description: ' The ID of the original template' + required: true + type: string + format: uuid + - name: version_id + in: path + description: The ID of the template version + required: true + type: string + format: uuid + get: + operationId: GET_templates-template_id-versions-version_id + summary: Retrieve a specific transactional template version. + tags: + - Transactional Templates Versions + description: '**This endpoint allows you to retrieve a specific version of a template.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/transactional_template_version_output' examples: application/json: - errors: - - field: null - message: authorization required + 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%> + generate_plain_content: true + subject: <%subject%> + updated_at: '2019-03-13 18:56:33' + editor: code security: - Authorization: [] - put: - operationId: PUT_subusers-subuser_name-monitor - summary: Update Monitor Settings for a subuser + patch: + operationId: PATCH_templates-template_id-versions-version_id + summary: Edit a transactional template version. tags: - - Subusers API - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - consumes: - - application/json - produces: - - application/json + - Transactional Templates Versions + description: '**This endpoint allows you to edit the content of your template version.**' parameters: - name: body in: body schema: - $ref: '#/definitions/monitor' + $ref: '#/definitions/transactional_template_version_create' example: - email: example@example.com - frequency: 500 + active: 1 + name: updated_example_name + html_content: <%body%> + plain_content: <%body%> + subject: <%subject%> + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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' + $ref: '#/definitions/transactional_template_version_output' examples: application/json: - errors: - - field: null - message: authorization required + 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%> + generate_plain_content: true + subject: <%subject%> + updated_at: '2019-03-13 18:56:33' + editor: code security: - Authorization: [] delete: - operationId: DELETE_subusers-subuser_name-monitor - summary: Delete monitor settings + operationId: DELETE_templates-template_id-versions-version_id + summary: Delete a transactional template version. tags: - - Subusers API - description: Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - produces: - - application/json + - Transactional Templates Versions + description: '**This endpoint allows you to delete a transactional template version.**' parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:authorizationHeader:Authorization' + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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 - /subusers/reputations: + security: + - Authorization: [] + /user/webhooks/event/settings: get: - operationId: GET_subusers-reputations - summary: Retrieve Subuser Reputations + operationId: GET_user-webhooks-event-settings + summary: Retrieve Event Webhook settings tags: - - Subusers API + - Webhooks 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 your current event webhook settings.** - This endpoint allows you to request the reputations for your subusers. - produces: - - application/json + If an event type is marked as `true`, then the event webhook will include information about that event. + + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. parameters: - - name: usernames - in: query - type: string + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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 + $ref: '#/definitions/event-webhook-response' examples: application/json: - - username: example_subuser - reputation: 99 - - username: example_subuser2 - reputation: 95.2 + enabled: false + url: incididunt reprehenderit + group_resubscribe: false + delivered: false + group_unsubscribe: false + spam_report: false + bounce: false + deferred: false + unsubscribe: true + processed: false + open: true + click: true + dropped: true + oauth_client_id: est fugiat + oauth_token_url: Duis in laborum sunt security: - Authorization: [] - '/subusers/{subuser_name}/ips': - parameters: - - name: subuser_name - in: path - required: true - type: string - put: - operationId: PUT_subusers-subuser_name-ips - summary: Update IPs assigned to a subuser + patch: + operationId: PATCH_user-webhooks-event-settings + summary: Update Event Notification Settings tags: - - Subusers API + - Webhooks 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. + **This endpoint allows you to update your current event webhook settings.** - More information: + If an event type is marked as `true`, then the event webhook will include information about that event. - * [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html) - * [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html) - consumes: - - application/json - produces: - - application/json + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. parameters: - name: body in: body schema: - type: array - description: The IP addresses you would like to assign to the subuser. - items: - type: string - format: ipv4 + $ref: '#/definitions/event-webhook-update-oauth-request' example: - - 127.0.0.1 - - $ref: '#/parameters/trait:authorizationHeader:Authorization' - responses: - '200': - description: '' - schema: - type: object - properties: - ips: - type: array - description: The IP addresses that are assigned to the subuser. - items: - type: string - format: ipv4 - examples: - application/json: - ips: - - 127.0.0.1 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '/subusers/{subuser_name}/stats/monthly': - parameters: - - name: subuser_name - in: path - required: true - type: string - get: - operationId: GET_subusers-subuser_name-stats-monthly - summary: Retrieve the monthly email statistics for a single subuser - tags: - - Subusers API - description: |- - **This endpoint allows you to retrive the monthly email statistics for a specific subuser.** - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: - `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`. - - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - produces: - - application/json - parameters: - - name: date - in: query - description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD - required: true - type: string - - name: sort_by_metric - in: query - description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.''' - required: false - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: limit - in: query - description: Optional field to limit the number of results returned. - required: false - type: integer - default: 5 - - name: offset - in: query - description: Optional beginning point in the list to retrieve from. - required: false - type: integer - default: 0 + enabled: false + url: id aliqua + group_resubscribe: true + delivered: false + group_unsubscribe: true + spam_report: true + bounce: false + deferred: false + unsubscribe: true + processed: false + open: false + click: false + dropped: false + oauth_client_id: reprehenderit in null + oauth_client_secret: ea in nostrud + oauth_token_url: cupidatat ad Ut + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/subuser_stats' + $ref: '#/definitions/event-webhook-response' examples: application/json: - date: '2016-02-01' - stats: - - first_name: John - last_name: Doe - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 5 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 10 - processed: 10 - requests: 10 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: user1 - type: subuser + enabled: true + url: mollit laborum + group_resubscribe: false + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: false + dropped: true + oauth_client_id: anim sunt + oauth_token_url: ex security: - Authorization: [] - /subusers/stats/monthly: + /user/webhooks/parse/settings: get: - operationId: GET_subusers-stats-monthly - summary: Retrieve monthly stats for all subusers + operationId: GET_user-webhooks-parse-settings + summary: Retrieve all parse settings tags: - - Subusers API - description: |- - **This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: - `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`. - - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - produces: - - application/json + - Webhooks + description: '**This endpoint allows you to retrieve all of your current inbound parse settings.**' parameters: - - name: date - in: query - description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD - required: true - type: string - - name: subuser - in: query - description: A substring search of your subusers. - required: false - type: string - - name: sort_by_metric - in: query - description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.''' - required: false - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: limit - in: query - description: Optional field to limit the number of results returned. - required: false - type: integer - default: 5 - - name: offset - in: query - description: Optional beginning point in the list to retrieve from. - required: false - type: integer - default: 0 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/subuser_stats' + type: object + properties: + result: + type: array + description: The list of your current inbound parse settings. + items: + $ref: '#/definitions/parse-setting' examples: application/json: - date: '2016-02-01' - stats: - - first_name: John - last_name: Doe - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 1 - processed: 0 - requests: 100 - spam_report_drops: 0 - spam_reports: 99 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: user1 - type: subuser - - first_name: Jane - last_name: Doe - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 5 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 10 - processed: 10 - requests: 10 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: user2 - type: subuser + result: + - url: 'http://mydomain.com/parse' + hostname: mail.mydomain.com + spam_check: true + send_raw: true + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /subusers/stats/sums: - get: - operationId: GET_subusers-stats-sums - summary: ' Retrieve the totals for each email statistic metric for all subusers.' + post: + operationId: POST_user-webhooks-parse-settings + summary: Create a parse setting tags: - - Subusers API + - Settings - Inbound Parse description: |- - **This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** + **This endpoint allows you to create a new inbound parse setting.** + Creating an Inbound Parse setting requires two pieces of information: a `url` and a `hostname`. - 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. + The `hostname` must correspond to a domain authenticated by Twilio SendGrid on your account. If you need to complete domain authentication, you can use the [Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth) or the #endpoint:aXpkWYramCg4ZNEGT endpoint. See "[How to Set Up Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/)" for instructions. - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - produces: - - application/json + Any email received by the `hostname` will be parsed when you complete this setup. You must also add a Twilio SendGrid MX record to this domain's DNS records. See "[Setting up the Inbound Parse Webhook](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/)" for full instructions. + + The `url` represents a location where the parsed message data will be delivered. Twilio SendGrid will make an HTTP POST request to this `url` with the message data. The `url` must be publicly reachable, and your application must return a `200` status code to signal that the message data has been received. parameters: - - name: sort_by_direction - in: query - description: 'The direction you want to sort. ' - required: false - type: string - default: desc - enum: - - desc - - asc - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - type: string - - name: end_date - in: query - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. - required: false - type: string - - name: limit - in: query - description: Limits the number of results returned per page. - required: false - type: integer - default: 5 - - name: offset - in: query - description: The point in the list to begin retrieving results from. - required: false - type: integer - default: 0 - - name: aggregated_by - in: query - description: How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD. - required: false - type: string - - name: sort_by_metric - in: query - description: The metric that you want to sort by. Must be a single metric. - required: false - type: string - default: delivered + - name: body + in: body + schema: + $ref: '#/definitions/parse-setting' + example: + hostname: myhostname.com + url: 'http://email.myhosthame.com' + spam_check: true + send_raw: false + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/category_stats' + $ref: '#/definitions/parse-setting' examples: application/json: - date: '2015-10-11' - stats: [] + url: 'http://email.myhostname.com' + hostname: myhostname.com + spam_check: false + send_raw: true + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - /subusers/stats: + /user/webhooks/parse/stats: get: - operationId: GET_subusers-stats - summary: Retrieve email statistics for your subusers. + operationId: GET_user-webhooks-parse-stats + summary: Retrieves Inbound Parse Webhook statistics. tags: - - Subusers API + - Webhooks 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. + **This endpoint allows you to retrieve the statistics for your Parse Webhook useage.** - 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. + 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 30MB in size, including all attachments. - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - produces: - - application/json + There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries). parameters: - name: limit in: query - description: Limits the number of results returned per page. + description: The number of statistics to return on each page. required: false - type: integer + type: string - name: offset in: query - description: The point in the list to begin retrieving results from. + description: The number of statistics to skip. required: false - type: integer + type: string - name: aggregated_by in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' + description: 'How you would like the statistics to by grouped. ' 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. + 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 to retrieve. Defaults to today. + description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD required: false type: string + default: The day the request is made. + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/stats' + 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-01' + - date: '2015-10-11' 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' + - metrics: + received: 0 + - date: '2015-10-12' 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' + - metrics: + received: 0 + - date: '2015-10-13' 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' + - metrics: + received: 0 + - date: '2015-10-14' 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' + - metrics: + received: 0 + - date: '2015-10-15' 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' + - metrics: + received: 0 + - date: '2015-10-16' 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' + - metrics: + received: 0 + - date: '2015-10-17' 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' + - metrics: + received: 0 + - date: '2015-10-18' 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' + - 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: - - 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' + - metrics: + received: 0 + - date: '2015-11-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 + - metrics: + received: 0 + - date: '2015-11-07' + stats: + - metrics: + received: 0 + - date: '2015-11-08' + stats: + - metrics: + received: 0 + - date: '2015-11-09' + stats: + - metrics: + received: 0 + - date: '2015-11-10' + stats: + - metrics: + received: 0 security: - Authorization: [] - /suppression/unsubscribes: + /user/webhooks/event/settings/signed: get: - operationId: GET_suppression-unsubscribes - summary: Retrieve all global suppressions + operationId: GET_user-webhooks-event-settings-signed + summary: Retrieve Signed Webhook Public Key tags: - - Suppressions - Global Suppressions + - Webhooks description: |- - **This endpoint allows you to retrieve a list of all email address that are globally suppressed.** + **This endpoint allows you to retrieve your signed webhook's public key.** - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - produces: - - application/json + Once you have enabled signing of the Event Webhook, you will need the public key provided to verify the signatures on requests coming from Twilio SendGrid. You can retrieve the public key from this endpoint at any time. + + For more information about cryptographically signing the Event Webhook, see [Getting Started with the Event Webhook Security Features](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features). parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive). - type: integer - - name: limit - in: query - description: The number of results to display on each page. - type: integer - - name: offset - in: query - description: The point in the list of results to begin displaying global suppressions. - type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the recipient was added to the global suppression list. - email: - type: string - description: The email address of the recipient who is globally suppressed. - required: - - created - - email + type: object + properties: + public_key: + type: string + description: The public key you can use to verify the Twilio SendGrid signature. + required: + - public_key examples: application/json: - - created: 1443651141 - email: user1@example.com - - created: 1443651154 - email: user2@example.com + public_key: anim quis in sint security: - Authorization: [] - /asm/suppressions/global: + patch: + operationId: PATCH_user-webhooks-event-settings-signed + summary: Enable/Disable Signed Webhook + tags: + - Webhooks + description: |- + **This endpoint allows you to enable or disable signing of the Event Webhook.** + + This endpoint takes a single boolean request parameter, `enabled`. You may either enable or disable signing of the Event Webhook using this endpoint. Once enabled, you can retrieve your public key using the `/webhooks/event/settings/signed` endpoint. + + For more information about cryptographically signing the Event Webhook, see [Getting Started with the Event Webhook Security Features](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features). + parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + required: + - enabled + example: + enabled: true + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + public_key: + type: string + description: The public key you can use to verify the Twilio SendGrid signature. + required: + - public_key + examples: + application/json: + public_key: voluptate id Excepteur proident + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: + - string + - 'null' + message: + type: string + required: + - message + examples: + application/json: + errors: + - message: mollit consequat dolore commodo + field: anim Ut + - message: qui + - message: commodo dolor ipsum + - message: minim fugiat amet + field: quis consectetur eiusmod ullamco laboris + '401': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: + - string + - 'null' + message: + type: string + required: + - message + examples: + application/json: + errors: + - message: fugiat + field: in proident + - message: adipisicing veniam laboris sunt ullamco + field: ut + - message: id sunt consequat Duis irure + - message: nisi + field: in qui + - message: tempor in eiusmod elit + '500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: + - string + - 'null' + message: + type: string + required: + - message + examples: + application/json: + errors: + - message: Excepteur culpa esse ea ut + - message: enim Excepteur dolore dolore + - message: dolor occaecat + security: + - Authorization: [] + /user/webhooks/event/test: post: - operationId: POST_asm-suppressions-global - summary: Add recipient addresses to the global suppression group. + operationId: POST_user-webhooks-event-test + summary: Test Event Notification Settings tags: - - Suppressions - Global Suppressions + - Webhooks description: |- - **This endpoint allows you to add one or more email addresses to the global suppressions group.** + **This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - consumes: - - application/json - produces: - - application/json + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + + >**Tip**: Retry logic for this endpoint differs from other endpoints, which use a rolling 24-hour retry. + + If your web server does not return a 2xx response type, we will retry a POST request until we receive a 2xx response or the maximum time of 10 minutes has expired. parameters: - name: body in: body schema: type: object properties: - recipient_emails: + url: + type: string + description: The URL where you would like the test notification to be sent. + oauth_client_id: + type: string + description: 'The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_client_secret and oauth_token_url fields.' + oauth_client_secret: + type: string + description: 'This secret is needed only once to create an access token. SendGrid will store this secret, allowing you to update your Client ID and Token URL without passing the secret to SendGrid again. When passing data in this field, you must also include the oauth_client_id and oauth_token_url fields.' + oauth_token_url: + type: string + description: 'The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id and oauth_client_secret fields.' + example: + url: mollit non ipsum magna + oauth_client_id: nisi + oauth_client_secret: veniam commodo ex sunt + oauth_token_url: dolor Duis + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + security: + - Authorization: [] + /messages: + get: + operationId: GET-messages + summary: Filter all messages + tags: + - Query + - Messages + description: |- + This is **BETA** functionality. You may not have access, and we reserve the right to change functionality without notice. + + Filter all messages to search your Email Activity. All queries need to be [URL encoded](https://meyerweb.com/eric/tools/dencoder/), and have this format: + + `query={query_type}="{query_content}"` + + encoded, this would look like this: + + `query=type%3D%22query_content%22` + + for example: + + Filter by a specific email - `query=to_email%3D%22example%40example.com%22` + + Filter by subject line - `query=subject%3d%22A%20Great%20Subject%22` + + **Full list of basic query types and examples:** + + + | **Filter query** | **Unencoded Example** (put this one into the try it out query - it'll automatically encode it for you) | **Encoded Example** (use this one in your code) | + |-----------------|----------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| + | msg_id | msg_id=“filter0307p1las1-16816-5A023E36-1.0” | msg_id%3D%22filter0307p1las1-16816-5A023E36-1.0%22 | + | from_email | from_email=“testing@sendgrid.net” | from_email%3D%22testing%40sendgrid.net%22 | + | subject | subject="This is a subject test" | subject%22This%20is%20a%20subject%20test%22 | + | to_email | to_email="example@example.com" | to_email%3D%22example%40example.com%22 | + | status | | status%22processed%22 | + | template_id | | | + | asm_group_id | | | + | api_key_id | | | + | events | status="processed" | status%3D%22processed%22 | + | originating_ip | | | + | categories | | | + | unique_args | | | + | outbound_ip | | | + | last_event_time | last_event_time=“2017-11-07T23:13:58Z” | last_event_time%3D%E2%80%9C2017-11-07T23%3A13%3A58Z%E2%80%9D | + | clicks | clicks="0" | clicks%3D%220%22 | + + For information about building compound queries, and for the full query language functionality, see the [query language reference](https://docs.google.com/a/sendgrid.com/document/d/1fWoKTFNfg5UUsB6t9KuIcSo9CetKF_T0bGfWJ_gdPCs/edit?usp=sharing). + + Coming soon, example compound queries: limit + to email + date + parameters: + - name: query + in: query + description: Use the query syntax to filter your email activity. + required: true + type: string + - name: limit + in: query + description: The number of messages returned. This parameter must be greater than 0 and less than or equal to 1000 + required: false + type: number + default: '10' + minimum: 1 + maximum: 1000 + - name: X-Query-Id + in: header + required: false + type: string + - name: X-Cursor + in: header + required: false + type: string + - $ref: '#/parameters/trait:authorizationHeader:Authorization' + responses: + '200': + description: '' + schema: + type: object + properties: + messages: type: array - description: 'The email address, or addresses, that you want to add to the global suppressions group.' items: - type: string - example: - recipient_emails: - - test1@example.com - - test2@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '201': + allOf: + - $ref: '#/definitions/email-activity-response-common-fields' + - type: object + properties: + opens_count: + type: integer + description: The number of times the message was opened. + clicks_count: + type: integer + description: The number of times links in the message were clicked. + last_event_time: + type: integer + description: A timestamp of the last event received for the specific message. + title: Abbv. Message + type: object + properties: + from_email: + type: string + msg_id: + type: string + subject: + type: string + to_email: + type: string + status: + type: string + enum: + - processed + - delivered + - not_delivered + opens_count: + type: integer + clicks_count: + type: integer + last_event_time: + type: string + description: iso 8601 format + required: + - from_email + - msg_id + - subject + - to_email + - status + - opens_count + - clicks_count + - last_event_time + example: + from_email: from@test.com + msg_id: abc123 + subject: anim Duis sint veniam + to_email: test@test.com + status: processed + opens_count: 1 + clicks_count: 2 + last_event_time: '2017-10-13T18:56:21Z' + examples: + application/json: + messages: + - from_email: from@test.com + msg_id: abc123 + subject: something profound + to_email: to@test.com + status: processed + opens_count: 0 + clicks_count: 0 + last_event_time: 1495064728 + last_timestamp: 1495064728 + - from_email: yeah@test.com + msg_id: 321befe + subject: something profound + to_email: nah@test.com + status: delivered + opens_count: 500 + clicks_count: 200 + last_event_time: 1495064793 + last_timestamp: 1495064793 + - from_email: sad@test.com + msg_id: 434512dfg + subject: something sad + to_email: reject@test.com + status: not delivered + opens_count: 0 + clicks_count: 0 + last_event_time: 1495064993 + last_timestamp: 1495064993 + '400': description: '' schema: type: object properties: - recipient_emails: + errors: type: array - description: The email addresses that are globally suppressed items: - type: string + type: object + properties: + message: + type: string + required: + - message required: - - recipient_emails + - errors examples: application/json: - recipient_emails: - - test1@example.com - - test2@example.com + errors: + - message: 'invalid syntax: ''bad_field'' is not a known field' + '429': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + examples: + application/json: + errors: + - message: too many requests security: - Authorization: [] - '/asm/suppressions/global/{email}': + '/messages/{msg_id}': parameters: - - name: email + - name: msg_id in: path - description: 'The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.' + description: The ID of the message you are requesting details for. required: true type: string get: - operationId: GET_asm-suppressions-global-email - summary: Retrieve a Global Suppression + operationId: GET-v3-messages-msg_id + summary: Filter messages by message ID tags: - - Suppressions - Global Suppressions + - Query + - Messages description: |- - **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.** - - If the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned. + This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice. - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + Get all of the details about the specified message. responses: '200': description: '' schema: - title: Retrieve a Global Suppression response + allOf: + - $ref: '#/definitions/email-activity-response-common-fields' + - type: object + example: + from_email: jane_doe@example.com + msg_id: in aliquip id aliqua + subject: est incididunt adipisicing pariatur + to_email: send@test.com + status: not delivered + template_id: 123e4567-e89b-12d3-a456-426655440000 + asm_group_id: 11376349 + teammate: '' + api_key_id: sdfsdfsdf123 + originating_ip: 2.3.4.5 + events: + - event_name: bounced + processed: 1492453589 + server_response: some error message + categories: + - hi + - bye + unique_args: '{''key'': ''value''}' + outbound_ip: 1.2.3.4 + outbound_ip_type: dedicated + properties: + template_id: + type: string + description: The ID associated with a Twilio SendGrid email template used to format the message. + asm_group_id: + type: integer + minimum: 1 + description: The unsubscribe group associated with this email. + teammate: + type: string + description: Teammate's username + minLength: 0 + maxLength: 64 + pattern: '^$|^[A-Za-z0-9]+' + api_key_id: + type: string + minLength: 3 + maxLength: 50 + pattern: '^[A-Za-z0-9]+' + description: The ID of the API Key used to authenticate the sending request for the message. + events: + type: array + description: List of events related to email message + items: + title: Event + type: object + example: + event_name: bounced + processed: '2017-10-13T18:56:21Z' + reason: some reason + url: 'http://3LX,MU}N=B8''d,K}>bEma{l~!ad%peIF}y>qHfLPWQ$l9b\!6.1H?$Z9H"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0"Q/-4dV"Yk3QGg[(O86=Pf"e17K4''r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\!6.1H?$Z9H"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0"Q/-4dV"Yk3QGg[(O86=Pf"e17K4''r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*O0OiStFG.ZoRi2=j%fUVa]&re6k{hKqD-8vWE12Fb5JC6z>S@@''cWS~w5KtuIwv$8/JDD94CXx1n5yjC_I2lQ66zDj4MXe/4bqlcqqQ7evnQWTYx5roaEYMapyuzb/USpsyalh/HcYc9PmQfF8ND_C7bXnwFQ_fb_BHMXbIV8JN28/NjZdawDJ6kSWxLykSVTHzcISGPBRfs_rt3Uc65Vzj6LDSSMN8WRs70m0tAWs/fkDvjvm_7ZeV08YZeB9j9mS9BcE089Fn5UzDlTJW9vqDF5uipjlIVrNbM7oWE/MIJcjg2vJO20jA24WHrchrEXCvKcxriviSDl3tuyDxqdqRSekpm2aH6yW7_ylXj/nWsex4jm3rKvYw1uLq3Tp7qb9edhj8B_TnwLv1yjHSkgbA5jKI4BTqxugmwVTnFf2OFCFp/ZILLkoKgfwOyIK4reUIkhCjuhkwp/cqGaFAkeCFQXPB6DLYesLZ2M3KPuBsBrs3pr3HRbTtwaOzdKtGc8e0C0VTjrJ3GwljStMPrSuQWh6/vigHRasZ4P9kFv5DPVbHWZzPvtwUw0AMByt44YH678WpbAXXy4I/IVOHmErZTbw1mJ/3vd4uI5rr2zEO_YA9qJZLJT/wmBimbOyaMtmTNYr_FhgfkKMN3_1la7RCK8CIP3p26mbuHbdJV1j/5sTIKibInM5l2BoWdEi49bPqzagsfjKpGVbg0YQ8mjrLhI92/qy0eVYi34kBGVuLzxK2FLC8vwYUrbupjUYE23Mc_6nmHYRK1HF1QmZDZG1hw96I3MPbTZqeJOWGch230qDNxOgnHRNNM52k/3c7FeuRr88RwZGpif/4FaSAbdqkUNvJ9J9qX2tJS9x5vZlgD8k4YHIXDztrnwg2VPquj/uo_2MjbWybIF/NGJM2RFAsKV1S5iOejuTV4p12KlH1p0Dt5EpxCSIl0XoWuvyLYar77f_hzqNdWAyL0FDxGfj4ma4jwqdTTLNyeZEtguYoCHTFfY/HgJkpHx/yO23G7gLhKPvD459ceffHidFh7LipTxNF0GFXhIAPrWfhv7PkPmVofBoFFlo6/rMcHQ82d5VS8i1CCyLtfuT5WH9GqrsOY7xo3lxi7BNL93/PLRdQT3SObRFRERw68V5ZFvIuEQqFOFZQ848rWPLXYDGY658dyjZALf/Ug4EROi_ehNtzPwecer_RGBHxeMnpxrPAFZEL6YXNKzm8hh3HY4Uc4fgkjge5fXsR4CeTSkS66/FOD00deDKmN7XcHEj1LGlAmd4XlV8vFpXg2VazX4OLW8z6vXn5vntNGYO6eBCEKUwupRz9nQSMeZ/Pbmjoopyt6TxQBUfPkHBdgCIhqA1zDV72ARqGlK_ao9KVjvgbB98YeiieIyogkuOa4y0E5iUEdBopzovVgtY88yLijh9ww/tl0R5rI2P2_OxguTbv_wrfEm8jRjISEIqSE9q29RB3n8PeD4hu24rcsaEuTMCqniiLN0a2OtZiKxHnbsNB660Aq3/tEo2SHZBkkIFYXBbDNE7gLfvFz9ZaC_E2oV2quyK1Id5SkNkJBVRRgROWBc_XEOXktc4vRUKxy1MQ526Xilyo8/uI67lHH1Vlr4V3GVmweT4A16KMqzmVzvRDRFLpkBv2iu3Okc1vIqkC/426aOqeUm6SXIx16d8BWVRcmqKqizxDEF3JkLFgX0ab73CZ4GdJ9YaakJO7y4adFGzzIVLcn08UZ/pwDQ9BAuwuMc2yMnKihdvmLKbnAa1ATk9jFXQ9QAEMBHZLbPNvtS3pkpk0s6fyh2ceHa9Myy3fL/oqvPmq_14KzLgPZHaOlyb3tUoQM52fv/I78TqTGyB4WYD_vkm8gYHZcCF0dFIXsiXUbAbwR90Ldk8lsgxSL6rBvjPSlQq7N66NPzUVRYr3zSISupG_66uS4rJszHwmxmmraT3/zfVKxHXFHgxUDRmnwIMfdFKm4sf/qnRRccOLExJYGcZy8u65jo4gHDvO6vnpsdf0YtVWqDBJXa95/Y/qL7EYS73_t6/2xnWra9TTO0OtQNXEQ1XXLSLt6vPw1FTlE2aYCitDgUo7DyxiwuGtvmMKUkYCo/lqXouo2TGXZFF80lrCu1vKdxBgOOerlrsKrOJawGEzL8XzXdxkOMUT8HOzHPNOvDwsxc47mvpVzXEbX5DRaioOlm2U4flTG/6bZfLqJqHNtrKwC5U5NNG6_yNOW5Jg_bLmzUosi86IXxn7i04vRXXn92JmdE70TcdujehT1n15wtiD8ld5A65IV2W1801/wr0XcDIGiUSmxFfCozUCtBTFwln0uJ0cquSDXhj7JQADhYDGyz8WhqcPE7CP9xN93EUBrWczINbA4IsfckY8CZh68/Tak5dEhw8i_3rz/8U39D/iML1G_A8TsnKQ9/_S8o89fFc7Wx/f1nXF8H6OLVbPpp5IZg7UTZ2K0bSe3iBpsmkkJpxY_6zEHTJE3LbIANwF9Ik5Tu0ZJpjck7I07xlHR8mDW9FXclSQC/qJUGL5qByf2SY2Wd24hqKGrahLfqApQuRI8_DtU/Y8kH6DDif5kD6as3sIe6VbKYnU9c1URq/npTlE72m107FXxW9zktdzbBJAxt4udMFzjt2LPcBpqrMKGkrg4BHqKXwhFTspCWyYCjxJ/eFb3fd3BB5kb9D0yl3oOjeWtbJBqsboyzdLisRBn2MCtXO2O8eo4Hkm/2uJDoRjRCyIi2GNRkH0B3EkN6Z3vG40C985bAtM8eqHABzP2QRcKCz4ICOw_Xz249bJk8qM0/m4EeIWnx2ISf9TBU6_0KZ5QJ0VPOCPXxV9jCeK5W5/RV5nd7GUUXG0btDqUAa3DzpaRHX3klMAqL73hK4AGD3ItikmxF8vnSaqtsgOCpEePERt9qcUOJJP2aR0scPAf_1TkGSrgr5VF/XLM2i7YhC_3J9fA2Qwa0dbTedY/xGayjimEkuWSWvh7P5FNOum_l7qJPnA31lQq6ixqR0NKhO328rWfijqKHF6WR/5O0MJ4WNuIXk6xBtTOA9mK7CGUgWjaF5mB72PVnDpN8G6ERO39GqO/fCO96/A1mwIPWedF6HklU8jaQ_M5EUzwCsBE3/7FW2hbcD3GCOFCiLvObjn59o6CKoYlmTop/PZw2CLzvARAr5KaLhjIuZRSKTGlmYjvSoSELuvWi/QHUV7SJ0kF_1O3b_3a88cm/z7qD3Rp6MmoQdGPSyu1lXTpoETypgOMywfsr4ycV2LQr5XaE3UrQP/RzobA4rI_I3ceCUaRASmil2rV1TUiyljhdCFt8zmi1o2NyTzSBRNGP0lXU5Qtm6dKKp7lGRC19P2oSSFrxt85vWRNo1mv8odcL/TF7/MN1Ev7gY20MqlRSBrlwg5LZ4_Az7QnBnpbU3LkTC/oVb743VFtXMW4cK/3lw6wfBJZe_8DobxT_6/gCXp6QOs/LuqmrQHMQvTS6jfbqVFnPfLjrQ01Mb_F4lr3md6m87wpc1CYd9hdzgUL/aqz68HMDCxjGauC00Rajq9wGVYcWJ3j6rIaHIPwclftjARXFDg0yH8v/L6qDgIgGwbB3eZfjOXHAMXRFNMMihseZxYkcFAzLtYr94q9XpQeK4bKi9h_rWAMwcEHnS8/MHHlySbgy8azGEA0u9xsY96MRi45Qe74kZ9xlsI1t4Yutx8/gsjIiu7vNsKEyeTwd88BMExjWNcJHOSHRff57pJBMEAtPdbMETYorvUkRyErsqprxX0W45n0RRQ85w/JCOsYaxZOAFfzO0AdLpMCguFwl01fkFOKYrQeXfNn8w0KF4XS0k/fPx02fU7fFjUoXcPH7_9xo755WL8DNIU2ne4b6DpiROe473yUfD8_zSNUI1tpxzVYNA7GvVSYt8UtqHn3/_QwuOc4VeAI6RiAG5O5bcAxzQl96Q35emNwtTT_CYqHORCmyPj6By2hT_SCLf8m_xFxxe3YzvnxDZGq3qf__pq7Tw181/GosBAJy3MotiIxcYDASbY9sV4T2V/KoGHyJ64spdkQbJOHJ216JMSKj8ii5m8gxqJ2ypL81p5hbjWtjbUgSc8M_KTLuc0Owf1R/3vr/dKbQ2pJ4XEfXhnZTBQY7ZrClnVCnd5cMe9ic/aNF0yyOSQVVOecUFkK9IYFVR8VHdVf4/Nfu3nOEskHki1_r3At1HLOMniS6qNTvhS0hfqIuBiQBsd5aB7OdfVpYy1HdIR72gMToBlpHPsE5GrVO0J9/gcyB2xcyZ3UpTom8G3V48LUkk6kcJ6l1SL5Fgzbst0z3pDA4dzBfswbC8dW57_MkswDANNd8atPrOBSU5m2z66dP/mIYQ8iq/DcmBexkARDI47VzYuw5gwy8Lvym2_B2gxBokU9_T/fHCPjlpqjTsY6SgBOz1nlDh_HcSWYAqnyrZxbEO2erVJ4WPKNzjM3KaPXGH/dZryna1E28wxCrMqLCs9aL9oVBlDMjUcEryAyRh7xwN0uWGopdpkd7Du6O9EPjAj37sHkUiVs7WL6JyexoDF_n67MICvQnJ9FK/FVrp1uMZnmr7ijkMW87moNRBkXbVc2EA_hHOHmpbVGqr6WgNtJ7bBk1LrAPT8sKtE75vbe_L9VYqBHJ/njk.WIIj-V23pwC7ZahcIL0XnDPupL7ltwEc779Ofhrk9dt_wIOFsA8XwnCjrYqH2ty.F0XdS"*;@kDYgfL4dwE/5I@>k|u0D:wGz"_8=}RJM!Ybbwd}eN=ZB*esF&(iQ%FW]_FSA:3Ze4O*6&tG-Fe**/j^a&S8zIa#6gxL2NmnNMSVGF-Bf3z08tt0ug_UfNshhs4HJh0l1o24gjAN-Uck1OvWkGQSXH0glB7CnOm0gI' + bounce_type: soft + mx_server: laborum nisi + http_user_agent: quis re + originating_ip: 204.173.18.0 + categories: + - dolor + - pie + unique_args: eu + outbound_ip: 181.40.184.87 + outbound_ip_type: dedicated + id: 2mMUdxV2HRfAeDiBTYs2IP + '400': + description: '' + schema: + errors: + - message: 'invalid syntax: ''bad_field'' is not a known field' + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + examples: + application/json: + errors: + - message: not found + field: message_id + '429': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + examples: + application/json: + errors: + - message: too many requests security: - Authorization: [] - delete: - operationId: DELETE_asm-suppressions-global-email - summary: Delete a Global Suppression + consumes: + - application/json + parameters: + - $ref: '#/parameters/trait:authorizationHeader:Authorization' + /messages/download: + post: + operationId: POST_v3-messages-download + summary: Request CSV tags: - - Suppressions - Global Suppressions + - CSV (UI only) + - V3 description: |- - **This endpoint allows you to remove an email address from the global suppressions group.** + This is BETA functionality. You may not have access, and we reserve the right to change functionality without notice. + + This request will kick off a backend process to generate a CSV file. Once generated, the worker will then send an email for the user download the file. The link will expire in 3 days. + + The CSV fill contain the last 1 million messages. This endpoint will be rate limited to 1 request every 12 hours (rate limit may change). - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + This endpoint is similar to the GET Single Message endpoint - the only difference is that /download is added to indicate that this is a CSV download requests but the same query is used to determine what the CSV should contain. parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - name: query + in: query + description: Uses a SQL like syntax to indicate which messages to include in the CSV + required: false + type: string + - $ref: '#/parameters/trait:authorizationHeader:Authorization' responses: - '204': + '202': + description: '' + schema: + type: object + properties: + status: + type: string + enum: + - pending + message: + type: string + examples: + application/json: + status: pending + message: An email will be sent to jane_doe@example.com when the CSV is ready to download. + '400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + examples: + application/json: + errors: + - message: some error + '429': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + examples: + application/json: + errors: + - message: too many requests + field: '' + '500': description: '' schema: type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + examples: + application/json: + errors: + - message: internal server error security: - Authorization: [] - '/asm/groups/{group_id}/suppressions': + '/messages/download/{download_uuid}': parameters: - - name: group_id + - name: download_uuid in: path - description: The id of the unsubscribe group that you are adding suppressions to. + description: |- + UUID used to locate the download csv request entry in the DB. + + This is the UUID provided in the email sent to the user when their csv file is ready to download required: true type: string - post: - operationId: POST_asm-groups-group_id-suppressions - summary: Add suppressions to a suppression group + format: uuid + get: + operationId: GET_v3-messages-download-download_uuid + summary: Download CSV tags: - - Suppressions - Suppressions - 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. - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body + - CSV (UI only) + - V3 + description: '**This endpoint will return a presigned URL that can be used to download the CSV that was requested from the #endpoint:LhbZ87Wq5k9AyFWD6 endpoint.**' + responses: + '200': + description: '' schema: type: object properties: - recipient_emails: + presigned_url: + type: string + format: uri + description: A signed link that will allow you to download the CSV file requested by the Request a CSV endpoint. + csv: + type: string + minLength: 5 + pattern: '^((http[s]?|ftp):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$' + description: Returns the aws signed link to the csv file which mako UI should perform a get on to trigger the csv download for the user + required: + - csv + examples: + application/json: + presigned_url: 'https://example.com' + csv: 'https://s3-us-west-2.amazonaws.com/sendgrid-rts-development-queries/013c31af-7c9a-49e6-922c-d990f4aff151.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAI4NOW7APZHRFYGWQ%2F20170728%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20170728T223936Z&X-Amz-Signature=5c13ede58b211799ab1a556280bd316c404eac3aef1450c47906a077166c4ab4' + '404': + description: '' + schema: + type: object + properties: + errors: type: array - description: The email address that you want to add to the unsubscribe group. items: - type: string - required: - - recipient_emails - example: - recipient_emails: - - test1@example.com - - test2@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '201': + type: object + properties: + message: + type: string + examples: + application/json: + errors: + - message: download token is invalid or expired + field: '' + '500': description: '' schema: type: object properties: - recipient_emails: + errors: type: array - description: The email address that were added to the suppressions list. items: - type: string - required: - - recipient_emails + type: object + properties: + message: + type: string examples: application/json: - recipient_emails: - - test1@example.com - - test2@example.com + errors: + - message: internal server error security: - Authorization: [] + parameters: + - $ref: '#/parameters/trait:authorizationHeader:Authorization' + /tracking_settings: get: - operationId: GET_asm-groups-group_id-suppressions - summary: Retrieve all suppressions for a suppression group + operationId: GET_tracking_settings + summary: Retrieve Tracking Settings tags: - - Suppressions - Suppressions - 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. - produces: - - application/json + - Settings - Tracking + description: '**This endpoint allows you to retrieve a list of all tracking settings on your account.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - description: The list of email addresses belonging to the given suppression group. - items: - type: string + type: object + properties: + result: + type: array + description: The list of all tracking settings. + items: + type: object + properties: + name: + type: string + description: The name of the event being tracked. + title: + type: string + description: The title of the tracking setting. + description: + type: string + description: A description about the event that is being tracked. + enabled: + type: boolean + description: Indicates if this tracking setting is currently enabled. examples: application/json: - - example@example.com - - example2@example.com + result: + - name: open + title: Open Tracking + description: lorem ipsum... . + enabled: true 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: - operationId: DELETE_asm-groups-group_id-suppressions-email - summary: Delete a suppression from a suppression group + /tracking_settings/click: + get: + operationId: GET_tracking_settings-click + summary: Retrieve Click Track Settings tags: - - Suppressions - Suppressions + - Settings - Tracking description: |- - **This endpoint allows you to remove a suppressed email address from the given suppression group.** + **This endpoint allows you to retrieve your current click tracking setting.** - 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. + Click Tracking overrides all the links and URLs in your emails and points them to either SendGrid’s servers or the domain with which you branded your link. When a customer clicks a link, SendGrid tracks those [clicks](https://sendgrid.com/docs/glossary/clicks/). + + Click tracking helps you understand how users are engaging with your communications. SendGrid can track up to 1000 links per email parameters: - - name: body - in: body - schema: - type: 'null' - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': + '200': description: '' schema: - type: 'null' + $ref: '#/definitions/click-tracking' + examples: + application/json: + enable_text: false + enabled: true security: - Authorization: [] - /asm/suppressions: - get: - operationId: GET_asm-suppressions - summary: Retrieve all suppressions + patch: + operationId: PATCH_tracking_settings-click + summary: Update Click Tracking Settings tags: - - Suppressions - Suppressions + - Settings - Tracking description: |- - **This endpoint allows you to retrieve a list of all suppressions.** + **This endpoint allows you to enable or disable your current click tracking setting.** - Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). - produces: - - application/json + Click Tracking overrides all the links and URLs in your emails and points them to either SendGrid’s servers or the domain with which you branded your link. When a customer clicks a link, SendGrid tracks those [clicks](https://sendgrid.com/docs/glossary/clicks/). + + Click tracking helps you understand how users are engaging with your communications. SendGrid can track up to 1000 links per email parameters: + - name: body + in: body + schema: + type: object + properties: + enabled: + type: boolean + description: The setting you want to use for click tracking. + example: + enabled: true - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - type: object - properties: - email: - type: string - description: The email address that was suppressed. - group_id: - type: integer - description: The id of the suppression group that this email address belongs to. - group_name: - type: string - description: The name of the suppression group that this email address belongs to. - created_at: - type: integer - description: A UNIX timestamp indicating when the suppression was created. - required: - - email - - group_id - - group_name - - created_at + $ref: '#/definitions/click-tracking' examples: application/json: - - email: test1@example.com - group_id: 1 - group_name: Weekly News - created_at: 1410986704 - - email: test1@example.com - group_id: 2 - group_name: Daily News - created_at: 1411493671 - - email: test2@example.com - group_id: 2 - group_name: Daily News - created_at: 1411493671 + enable_text: false + enabled: true security: - Authorization: [] - '/asm/suppressions/{email}': - parameters: - - name: email - in: path - description: The email address that you want to search suppression groups for. - required: true - type: string + /tracking_settings/google_analytics: get: - operationId: GET_asm-suppressions-email - summary: Retrieve all suppression groups for an email address + operationId: GET_tracking_settings-google_analytics + summary: Retrieve Google Analytics Settings tags: - - Suppressions - Suppressions - description: |- - **This endpoint returns the list of all groups that the given email address has been unsubscribed from.** - - Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - type: object - properties: - suppressions: - type: array - description: The array of suppression groups. - items: - type: object - properties: - description: - type: string - description: The description of the suppression group. - id: - type: integer - description: The id of the suppression group. - is_default: - type: boolean - description: Indicates if the suppression group is set as the default. - name: - type: string - description: The name of the suppression group. - suppressed: - type: boolean - description: Indicates if the given email address is suppressed for this group. - required: - - description - - id - - is_default - - name - - suppressed - required: - - suppressions + - Settings - Tracking + description: |- + **This endpoint allows you to retrieve your current setting for Google Analytics.** + + + Google Analytics helps you understand how users got to your site and what they're doing there. 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/ui/analytics-and-reporting/google-analytics/). + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/google_analytics_settings' examples: application/json: - suppressions: - - description: Optional description. - id: 1 - is_default: true - name: Weekly News - suppressed: true - - description: Some daily news. - id: 2 - is_default: true - name: Daily News - suppressed: true - - description: An old group. - id: 2 - is_default: false - name: Old News - suppressed: false + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' security: - Authorization: [] - '/asm/groups/{group_id}/suppressions/search': - parameters: - - name: group_id - in: path - description: The ID of the suppression group that you would like to search. - required: true - type: string - post: - operationId: POST_asm-groups-group_id-suppressions-search - summary: Search for suppressions within a group + patch: + operationId: PATCH_tracking_settings-google_analytics + summary: Update Google Analytics Settings tags: - - Suppressions - Suppressions + - Settings - Tracking description: |- - **This endpoint allows you to search a suppression group for multiple suppressions.** + **This endpoint allows you to update your current setting for Google Analytics.** - When given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group. + Google Analytics helps you understand how users got to your site and what they're doing there. 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). - Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). - consumes: - - application/json - produces: - - application/json + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/ui/analytics-and-reporting/google-analytics/). parameters: - name: body in: body schema: - type: object - properties: - recipient_emails: - type: array - description: The list of email address that you want to search the suppression group for. - items: - type: string - required: - - recipient_emails + $ref: '#/definitions/google_analytics_settings' example: - recipient_emails: - - exists1@example.com - - exists2@example.com - - doesnotexists@example.com + enabled: true + utm_source: sendgrid.com + utm_medium: email + utm_term: '' + utm_content: '' + utm_campaign: website - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - recipient_emails: - type: array - description: The email address from your search that do exist in the suppression group. - items: - type: string - required: - - recipient_emails + $ref: '#/definitions/google_analytics_settings' examples: application/json: - recipient_emails: - - exists1@example.com - - exists2@example.com + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' security: - Authorization: [] - /asm/groups: + /tracking_settings/open: get: - operationId: GET_asm-groups - summary: Retrieve information about multiple suppression groups + operationId: GET_tracking_settings-open + summary: Get Open Tracking Settings tags: - - Suppressions - Unsubscribe Groups + - Settings - Tracking description: |- - **This endpoint allows you to retrieve information about multiple suppression groups.** + **This endpoint allows you to retrieve your current settings for open tracking.** - This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID. + Open Tracking adds an invisible image at the end of the email which can track email opens. - Suppressions are a list of email addresses that will not receive content sent under a given [group](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). + 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. - Suppression groups, or [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html), allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue recieving your transactional email witout having to receive your marketing content. - produces: - - application/json + These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. parameters: - - name: id - in: query - description: The ID of a suppression group that you want to retrieve information for. - type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/suppression_group' + type: object + properties: + enabled: + type: boolean + description: Indicates if open tracking is enabled. + required: + - enabled examples: application/json: - - id: 100 - name: Newsletters - description: Our monthly newsletter. - last_email_sent_at: null - is_default: true - unsubscribes: 400 - - id: 101 - name: Alerts - description: Emails triggered by user-defined rules. - last_email_sent_at: null - is_default: false - unsubscribes: 1 + enabled: true security: - Authorization: [] - post: - operationId: POST_asm-groups - summary: Create a new suppression group + patch: + operationId: PATCH_tracking_settings-open + summary: Update Open Tracking Settings tags: - - Suppressions - Unsubscribe Groups + - Settings - Tracking description: |- - **This endpoint allows you to create a new suppression group.** + **This endpoint allows you to update your current settings for open tracking.** - 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. + Open Tracking adds an invisible image at the end of the email which can track email opens. - The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + 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. - Each user can create up to 25 different suppression groups. - consumes: - - application/json - produces: - - application/json + These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. parameters: - name: body in: body schema: type: object properties: - name: - type: string - description: The name that you would like to use for your new suppression group. - maxLength: 30 - description: - type: string - description: A brief description of your new suppression group. - maxLength: 100 - is_default: + enabled: type: boolean - description: Indicates if you would like this to be your default suppression group. - required: - - name - - description + description: The new status that you want to set for open tracking. example: - name: Product Suggestions - description: Suggestions for products our users might like. - is_default: true + enabled: true - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': + '200': description: '' schema: type: object properties: - id: - type: integer - description: The ID of the suppression group. - name: - type: string - description: The name of the suppression group. - description: - type: string - description: A brief description of the suppression group. - is_default: + enabled: type: boolean - description: Indicates if this is the default suppression group. + description: Indicates if open tracking is enabled. required: - - id - - name - - description - - is_default + - enabled examples: application/json: - id: 103 - name: Product Suggestions - description: Suggestions for products our users might like. - is_default: false + enabled: true security: - Authorization: [] - '/asm/groups/{group_id}': - parameters: - - name: group_id - in: path - description: The ID of the suppression group you would like to retrieve. - required: true - type: string + /tracking_settings/subscription: get: - operationId: GET_asm-groups-group_id - summary: Get information on a single suppression group. + operationId: GET_tracking_settings-subscription + summary: Retrieve Subscription Tracking Settings tags: - - Suppressions - Unsubscribe Groups + - Settings - Tracking 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. + **This endpoint allows you to retrieve your current settings for subscription tracking.** - Each user can create up to 25 different suppression groups. - produces: - - application/json + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - description: - type: string - description: The description of the suppression group. - id: - type: integer - description: The ID of the suppression group. - is_default: - type: boolean - description: Indicates if this is the default suppression group. - last_email_sent_at: - type: 'null' - description: A unix timestamp indicating the last time this group was assigned to an email. - name: - type: string - description: The name of the suppression group. - unsubscribes: - type: integer - description: 'The number of unsubscribes, or suppressions, in this group.' + $ref: '#/definitions/subscription_tracking_settings' examples: application/json: - description: Our monthly newsletter. - id: 100 - is_default: true - last_email_sent_at: null - name: Newsletters - unsubscribes: 400 + enabled: true + html_content: | +

Something something unsubscribe <% %> something something

+ landing: | +

subscribehere

+ plain_content: Something something unsubscribe <% %> something something + replace: thetag + url: '' security: - Authorization: [] patch: - operationId: PATCH_asm-groups-group_id - summary: Update a suppression group. + operationId: PATCH_tracking_settings-subscription + summary: Update Subscription Tracking Settings + tags: + - Settings - Tracking + 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. + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/subscription_tracking_settings' + example: + enabled: true + landing: landing page html + url: url + replace: replacement tag + html_content: html content + plain_content: text content + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/subscription_tracking_settings' + examples: + application/json: + enabled: true + landing: landing page html + url: url + replace: replacement tag + html_content: html content + plain_content: text content + security: + - Authorization: [] + /stats: + get: + operationId: GET_stats + summary: Retrieve global email statistics tags: - - Suppressions - Unsubscribe Groups + - Stats 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. + **This endpoint allows you to retrieve all of your global email statistics between a given date range.** - Each user can create up to 25 different suppression groups. - consumes: - - application/json - produces: - - application/json + Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. parameters: - - name: body - in: body - schema: - type: object - properties: - id: - type: integer - description: The id of the suppression group. - name: - type: string - description: The name of the suppression group. Each group created by a user must have a unique name. - maxLength: 30 - description: - type: string - description: The description of the suppression group. - maxLength: 100 - is_default: - type: boolean - description: Indicates if the suppression group is set as the default group. - required: - - name - example: - id: 103 - name: Item Suggestions - description: Suggestions for items our users might like. - - $ref: '#/parameters/trait:authorizationHeader:Authorization' - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date' responses: - '201': + '200': description: '' schema: - $ref: '#/definitions/suppression_group' + 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: + $ref: '#/definitions/stats-advanced-global-stats' + required: + - date + - stats examples: application/json: - id: 103 - name: Item Suggestions - description: Suggestions for items our users might like. - delete: - operationId: DELETE_asm-groups-group_id - summary: Delete a suppression group. + - date: '2015-11-03' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-04' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-05' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-06' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-07' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-08' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-09' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + security: + - Authorization: [] + /geo/stats: + get: + operationId: GET_geo-stats + summary: Retrieve email statistics by country and state/province. tags: - - Suppressions - Unsubscribe Groups + - Stats 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. + **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** - The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + **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. - Each user can create up to 25 different suppression groups. - produces: - - application/json + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). parameters: - - name: body - in: body - schema: - type: 'null' + - name: country + in: query + description: The country you would like to see statistics for. Currently only supported for US and CA. + type: string + enum: + - US + - CA - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date' responses: - '204': + '200': description: '' schema: - type: object - security: - - Authorization: [] - /scopes/requests: + 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: + $ref: '#/definitions/advanced_stats_clicks_opens' + 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 + /devices/stats: get: - operationId: GET_v3-scopes-requests - summary: Retrieve access requests + operationId: GET_devices-stats + summary: Retrieve email statistics by device type. tags: - - Teammates - description: |- - This endpoint allows you to retrieve a list of all recent access requests. - - **Note:** The Response Header's 'link' parameter will include pagination info. For example: - - link: ```; rel="first"; title="1", ; rel="last"; title="2", ; rel="prev"; title="1"``` - produces: - - application/json + - Stats + 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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/)." parameters: - - name: limit - in: query - description: Optional field to limit the number of results returned. - type: integer - default: 50 - - name: offset - in: query - description: Optional beginning point in the list to retrieve from. - type: integer - default: 0 + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date' responses: '200': description: '' @@ -12470,830 +20177,1139 @@ paths: items: type: object properties: - id: - type: integer - description: Request ID - scope_group_name: - type: string - description: Name of group of scopes associated to page teammate is requesting access to - username: - type: string - description: Teammate's username - email: - type: string - description: Teammate's email - first_name: - type: string - description: Teammate's first name - last_name: + date: type: string - description: Teammate's last name - examples: - application/json: - - id: 1 - scope_group_name: Mail Settings - username: teammate1 - email: teammate1@example.com - first_name: Teammate - last_name: One - - id: 2 - scope_group_name: Stats - username: teammate2 - email: teammate2@example.com - first_name: Teammate - last_name: Two - security: - - Authorization: [] - '/scopes/requests/{request_id}': - parameters: - - name: request_id - in: path - description: The ID of the request that you want to deny. - required: true - type: string - delete: - operationId: DELETE_v3-scopes-requests-request_id - summary: Deny access request - tags: - - Teammates - description: |- - This endpoint allows you to deny an attempt to access your account. - - **Note:** Only teammate admins may delete a teammate's access request. - consumes: - - application/json - produces: - - application/json - responses: - '204': - description: '' - '401': - description: '' - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - 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: + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - errors: - - message: Cannot find request - field: request_id + - 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 security: - Authorization: [] - '/scopes/requests/{request_id}/approve': - parameters: - - name: request_id - in: path - description: The ID of the request that you want to approve. - required: true - type: string - patch: - operationId: PATCH_v3-scopes-requests-approve-id - summary: Approve access request + /clients/stats: + get: + operationId: GET_clients-stats + summary: Retrieve email statistics by client type. tags: - - Teammates + - Stats description: |- - This endpoint allows you to approve an access attempt. + **This endpoint allows you to retrieve your email statistics segmented by client type.** - **Note:** Only teammate admins may approve another teammate’s access request. - consumes: - - application/json - produces: - - application/json - responses: - '200': - description: '' - schema: - type: object - properties: - scope_group_name: - type: string - description: name of feature teammate will be given access to - examples: - application/json: - scope_group_name: Stats - '401': - description: '' - schema: - type: object - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string - security: - - Authorization: [] - '/teammates/pending/{token}/resend': - parameters: - - name: token - in: path - description: The token for the invite that you want to resend. - required: true - type: string - post: - operationId: POST_v3-teammates-pending-token-resend - summary: Resend teammate invite - tags: - - Teammates - description: |- - This endpoint allows you to resend a teammate invite. + **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. - **Note:** Teammate invitations will expire after 7 days. Resending an invite will reset the expiration date. - consumes: - - application/json - produces: - - application/json + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/). + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:statsAdvancedStatsBaseQueryStrings:start_date' + - $ref: '#/parameters/trait:statsAdvancedStatsBaseQueryStrings:end_date' + - $ref: '#/parameters/trait:statsAdvancedStatsBaseQueryStrings:aggregated_by' responses: '200': description: '' schema: - type: object - properties: - token: - type: string - description: ID to identify invite - email: - type: string - description: Teammate's email address - scopes: - type: array - description: Initial set of permissions to give to teammate if they accept the invite - items: + type: array + items: + type: object + properties: + date: type: string - is_admin: - type: boolean - description: Set to true if teammate should have admin privileges - examples: - application/json: - pending_id: abc123abc - email: teammate1@example.com - scopes: - - user.profile.read - - user.profile.update - is_admin: false - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string - examples: - application/json: - errors: - - message: invalid pending key - field: pending_key - security: - - Authorization: [] - /teammates/pending: - get: - operationId: GET_v3-teammates-pending - summary: Retrieve all pending teammates - tags: - - Teammates - description: |- - This endpoint allows you to retrieve a list of all pending teammate invitations. - - **Note:** Each teammate invitation is valid for 7 days. Users may resend the invite to refresh the expiration date. - consumes: - - application/json - produces: - - application/json - responses: - '200': - description: '' - schema: - type: object - properties: - result: - type: array - items: - type: object - properties: - email: - type: string - description: Email address teammate invite will be sent to - scopes: - type: array - description: List of permissions to give teammate if they accept - items: + description: The date that the statistics were gathered. + stats: + type: array + description: The list of statistics. + items: + type: object + properties: + type: type: string - is_admin: - type: boolean - description: Set to true to indicate teammate should have the same set of permissions as parent user - token: - type: string - description: Invitation token used to identify user - expiration_date: - type: integer - description: timestamp indicates when invite will expire. Expiration is 7 days after invite creation + description: The type of segmentation. + name: + type: string + description: The name of the specific segmentation. + metrics: + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - result: - - email: user1@example.com - scopes: - - user.profile.read - - user.profile.edit - is_admin: false - pending_id: abcd123abc - expiration_date: 1456424263 - - email: user2@example.com - scopes: [] - is_admin: true - pending_id: bcde234bcd - expiration_date: 1456424263 + - date: '2014-10-01' + stats: + - metrics: + opens: 1 + unique_opens: 1 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: + opens: 0 + unique_opens: 0 + name: Gmail + type: client security: - Authorization: [] - '/teammates/pending/{token}': + '/clients/{client_type}/stats': parameters: - - name: token + - name: client_type in: path - description: The token for the invite you want to delete. + description: 'Specifies the type of client to retrieve stats for. Must be either "phone", "tablet", "webmail", or "desktop".' required: true type: string - delete: - operationId: DELETE_v3-teammates-pending-token - summary: Delete pending teammate - tags: - - Teammates - description: This endpoint allows you to delete a pending teammate invite. - consumes: - - application/json - produces: - - application/json - responses: - '204': - description: '' - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string - security: - - Authorization: [] - /teammates: - post: - operationId: POST_v3-teammates - summary: Invite teammate + enum: + - phone + - tablet + - webmail + - desktop + get: + operationId: GET_clients-client_type-stats + summary: Retrieve stats by a specific client type. tags: - - Teammates + - Stats description: |- - This endpoint allows you to send a teammate invitation via email with a predefined set of scopes, or permissions. + **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** - **Note:** A teammate invite will expire after 7 days, but you may resend the invite at any time to reset the expiration date. + **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. - Essentials, [Legacy Lite](https://sendgrid.com/docs/Classroom/Basics/Billing/legacy_lite_plan.html), and Free Trial users may create up to one teammate per account. There are no limits for how many teammates a Pro or higher account may create. - consumes: - - application/json - produces: - - application/json + ## Available Client Types + - phone + - tablet + - webmail + - desktop + + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/). parameters: - - name: body - in: body - schema: - type: object - properties: - email: - type: string - description: New teammate's email - minLength: 5 - maxLength: 255 - pattern: ^.*@.*\..* - scopes: - type: array - description: Set to specify list of scopes that teammate should have. Should be empty if teammate is an admin. - items: - type: string - is_admin: - type: boolean - default: false - description: Set to true if teammate should be an admin user - required: - - email - - scopes - - is_admin - example: - email: teammate1@example.com - scopes: - - user.profile.read - - user.profile.update - is_admin: false + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:statsAdvancedStatsBaseQueryStrings:start_date' + - $ref: '#/parameters/trait:statsAdvancedStatsBaseQueryStrings:end_date' + - $ref: '#/parameters/trait:statsAdvancedStatsBaseQueryStrings:aggregated_by' responses: - '201': + '200': description: '' schema: - type: object - properties: - token: - type: string - description: Token to identify invite - email: - type: string - description: Teammate's email address - scopes: - type: array - description: Initial set of permissions to give to teammate if they accept the invite - items: {} - is_admin: - type: boolean - description: Set to true if teammate should have admin privileges + 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: + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - email: teammate1@example.com - scopes: - - user.profile.read - - user.profile.update - is_admin: false - '400': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string + - date: '2014-10-01' + stats: + - metrics: + opens: 1 + unique_opens: 1 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: + opens: 0 + unique_opens: 0 + name: Gmail + type: client security: - Authorization: [] + /mailbox_providers/stats: get: - operationId: GET_v3-teammates - summary: Retrieve all teammates + operationId: GET_mailbox_providers-stats + summary: Retrieve email statistics by mailbox provider. tags: - - Teammates + - Stats description: |- - This endpoint allows you to retrieve a list of all current teammates. + **This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.** - **Note:** The Response Header will include pagination info. For example: + **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. - link: ```; rel="first"; title="1", ; rel="last"; title="2", ; rel="prev"; title="1"``` + 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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/). parameters: - - name: limit - in: query - description: Number of items to return - type: integer - default: 500 - minimum: 0 - maximum: 500 - - name: offset + - name: mailbox_providers in: query - description: Paging offset - type: integer - default: 0 - minimum: 0 + description: The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times. + type: string + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date' responses: '200': description: '' schema: - type: object - properties: - result: - type: array - items: - type: object - properties: - username: - type: string - description: Teammate's username - email: - type: string - description: Teammate's email - first_name: - type: string - description: Teammate's first name - last_name: - type: string - description: Teammate's last name - user_type: - type: string - description: 'Indicate the type of user: owner user, teammate admin user, or normal teammate' - enum: - - admin - - owner - - teammate - is_admin: - type: boolean - description: Set to true if teammate has admin privileges - phone: - type: string - description: (optional) Teammate's phone number - website: - type: string - description: (optional) Teammate's website - address: - type: string - description: (optional) Teammate's address - address2: - type: string - description: (optional) Teammate's address - city: - type: string - description: (optional) Teammate's city - state: - type: string - description: (optional) Teammate's state - zip: - type: string - description: (optional) Teammate's zip - country: - type: string - description: (optional) Teammate's country + 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: + $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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 0 + 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 0 + 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 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 + processed: 0 + requests: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 security: - Authorization: [] - '/teammates/{username}': - parameters: - - name: username - in: path - description: The username of the teammate that you want to retrieve. - required: true - type: string + /browsers/stats: get: - operationId: GET_v3-teammates-username - summary: Retrieve specific teammate - tags: - - Teammates - description: This endpoint allows you to retrieve a specific teammate by username. - produces: - - application/json - responses: - '200': - description: '' - schema: - type: object - properties: - username: - type: string - description: Teammate's username - first_name: - type: string - description: Teammate's first name - last_name: - type: string - description: Teammate's last name - email: - type: string - description: Teammate's email - scopes: - type: array - description: Scopes associated to teammate - items: {} - user_type: - type: string - description: 'Indicate the type of user: account owner, teammate admin user, or normal teammate' - enum: - - admin - - owner - - teammate - is_admin: - type: boolean - description: Set to true if teammate has admin privileges - phone: - type: string - description: (optional) Teammate's phone number - website: - type: string - description: (optional) Teammate's website - address: - type: string - description: (optional) Teammate's address - address2: - type: string - description: (optional) Teammate's address - city: - type: string - description: (optional) Teammate's city - state: - type: string - description: (optional) Teammate's state - zip: - type: string - description: (optional) Teammate's zip - country: - type: string - description: (optional) Teammate's country - examples: - application/json: - username: teammate1 - first_name: Jane - last_name: Doe - email: teammate1@example.com - scopes: - - user.profile.read - - user.profile.update - - ... - user_type: admin - is_admin: true - phone: 123-345-3453 - website: www.example.com - company: ACME Inc. - address: 123 Acme St - address2: '' - city: City - state: CA - country: USA - zip: '12345' - security: - - Authorization: [] - patch: - operationId: PATCH_v3-teammates-username - summary: Update teammate's permissions + operationId: GET_browsers-stats + summary: Retrieve email statistics by browser. tags: - - Teammates + - Stats description: |- - This endpoint allows you to update a teammate’s permissions. - - To turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have. + **This endpoint allows you to retrieve your email statistics segmented by browser type.** - **Only the parent user or other admin teammates can update another teammate’s permissions.** + **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. - **Admin users can only update permissions.** - consumes: - - application/json - produces: - - application/json + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/). parameters: - - name: body - in: body - schema: - type: object - properties: - scopes: - type: array - description: 'Provide list of scopes that should be given to teammate. If specifying list of scopes, is_admin should be set to False.' - items: - type: string - is_admin: - type: boolean - description: 'Set to True if this teammate should be promoted to an admin user. If True, scopes should be an empty array.' - required: - - scopes - - is_admin - example: - scopes: - - user.profile.read - - user.profile.edit - is_admin: false + - 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. + type: string + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date' + - $ref: '#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date' responses: '200': description: '' schema: - type: object - properties: - username: - type: string - description: Teammate's username - first_name: - type: string - description: Teammate's first name - last_name: - type: string - description: Teammate's last name - email: - type: string - description: Teammate's email address - scopes: - type: array - description: Scopes given to teammate - items: - type: string - user_type: - type: string - description: 'Indicate the type of user: owner user, teammate admin user, or normal teammate' - enum: - - admin - - owner - - teammate - is_admin: - type: boolean - description: Set to true if teammate has admin priveleges - phone: - type: string - description: (optional) Teammate's phone number - website: - type: string - description: (optional) Teammate's website - address: - type: string - description: (optional) Teammate's address - address2: - type: string - description: (optional) Teammate's address - city: - type: string - description: (optional) Teammate's city - state: - type: string - description: (optional) Teammate's state - zip: - type: string - description: (optional) Teammate's zip - country: - type: string - description: (optional) Teammate's country - examples: - application/json: - username: teammate1 - first_name: Jane - last_name: Doe - email: teammate1@example.com - scopes: - - user.profile.read - - user.profile.edit - user_type: teammate - is_admin: false - phone: 123-345-3453 - website: www.example.com - company: ACME Inc. - address: 123 Acme St - address2: '' - city: City - state: CA - country: USA - zip: '12345' - '400': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string - examples: - application/json: - errors: - - message: one or more of given scopes are invalid - field: scopes - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string + 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: + $ref: '#/definitions/advanced_stats_clicks' examples: application/json: - errors: - - message: username not found - field: username + - date: '2014-10-01' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser + - date: '2014-10-02' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser security: - Authorization: [] - delete: - operationId: DELETE_v3-teammates-username - summary: Delete teammate + /suppression/bounces: + get: + operationId: GET_suppression-bounces + summary: Retrieve all bounces tags: - - Teammates - description: |- - This endpoint allows you to delete a teammate. - - **Only the parent user or an admin teammate can delete another teammate.** - consumes: - - application/json - produces: - - application/json + - Bounces API + description: '**This endpoint allows you to retrieve all of your bounces.**' + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). + type: integer + - name: Accept + in: header + required: true + type: string + default: application/json + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string - '404': + '200': description: '' schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - field: - type: string + type: array + items: + $ref: '#/definitions/bounce_response' examples: application/json: - errors: - - message: username not found - field: username + - 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_error_response_schema' security: - Authorization: [] - /templates: - post: - operationId: POST_templates - summary: Create a transactional template. + delete: + operationId: DELETE_suppression-bounces + summary: Delete bounces tags: - - Transactional Templates + - Bounces API description: |- - **This endpoint allows you to create a transactional template.** + **This endpoint allows you to delete all emails on your bounces list.** - 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. + There are two options for deleting bounced emails: - 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). - consumes: - - application/json - produces: - - application/json + 1. You can delete all bounced emails by setting `delete_all` to `true` in the request body. + 2. You can delete a selection of bounced emails by specifying the email addresses in the `emails` array of the request body. parameters: - name: body in: body schema: type: object properties: - name: - type: string - description: The name for the new transactional template. - maxLength: 100 - required: - - name + 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 example: - name: example_name + delete_all: false + emails: + - example@example.com + - example2@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': + '204': description: '' schema: - $ref: '#/definitions/transactional_template' + type: 'null' + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' examples: application/json: - id: 733ba07f-ead1-41fc-933a-3976baa23716 - name: example_name - versions: [] + errors: + - field: null + message: authorization required security: - Authorization: [] + '/suppression/bounces/{email}': + parameters: + - name: email + in: path + required: true + type: string get: - operationId: GET_templates - summary: Retrieve all transactional templates. + operationId: GET_suppression-bounces-email + summary: Retrieve a Bounce tags: - - 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). - produces: - - application/json + - Bounces API + description: '**This endpoint allows you to retrieve a specific bounce by email address.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: @@ -13302,4175 +21318,4934 @@ paths: schema: type: array items: - $ref: '#/definitions/transactional_template' + $ref: '#/definitions/bounce_response' + examples: + application/json: + - created: 1443651125 + email: bounce1@test.com + reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ' + status: 5.1.1 security: - Authorization: [] - '/templates/{template_id}': - parameters: - - name: template_id - in: path - description: The id of the transactional template you want to retrieve. - required: true - type: string - get: - operationId: GET_templates-template_id - summary: Retrieve a single transactional template. + delete: + operationId: DELETE_suppression-bounces-email + summary: Delete a bounce tags: - - Transactional Templates - 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). - produces: - - application/json + - Bounces API + description: '**This endpoint allows you to remove an email address from your bounce list.**' parameters: + - name: email_address + in: query + description: The email address you would like to remove from the bounce list. + required: true + type: string + format: email + - name: body + in: body + schema: + type: 'null' - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' schema: - $ref: '#/definitions/transactional_template' + type: object + '401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + examples: + application/json: + errors: + - field: null + message: authorization required security: - Authorization: [] - patch: - operationId: PATCH_templates-template_id - summary: Edit a transactional template. + /suppression/blocks: + get: + operationId: GET_suppression-blocks + summary: Retrieve all blocks tags: - - Transactional Templates - 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). - consumes: - - application/json - produces: - - application/json + - Blocks API + description: '**This endpoint allows you to retrieve all email addresses that are currently on your blocks list.**' parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - description: The name of the transactional template. - maxLength: 100 - example: - name: new_example_name + - name: start_time + in: query + description: The start of the time range when a blocked email was created (inclusive). This is a unix timestamp. + type: integer + - name: end_time + in: query + description: The end of the time range when a blocked email was created (inclusive). This is a unix timestamp. + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: The point in the list to begin displaying results. + type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/transactional_template' + $ref: '#/definitions/blocks-response' examples: application/json: - id: 733ba07f-ead1-41fc-933a-3976baa23716 - name: new_example_name - versions: [] + - created: 1443651154 + email: example@example.com + reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' + status: 4.0.0 + - created: 1443651155 + email: example1@example.com + reason: 'unable to resolve MX record for example.com: servfail' + status: 4.0.0 security: - Authorization: [] delete: - operationId: DELETE_templates-template_id - summary: Delete a template. + operationId: DELETE_suppression-blocks + summary: Delete blocks tags: - - Transactional Templates + - Blocks API description: |- - **This endpoint allows you to delete a transactional template.** + **This endpoint allows you to delete all email addresses on your blocks list.** - 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. + There are two options for deleting blocked emails: - 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). + 1. You can delete all blocked emails by setting `delete_all` to `true` in the request body. + 2. You can delete a selection of blocked emails by specifying the email addresses in the `emails` array of the request body. parameters: - name: body in: body schema: - type: 'null' + type: object + properties: + delete_all: + type: boolean + description: Indicates if you want to delete all blocked email addresses. + emails: + type: array + description: The specific blocked email addresses that you want to delete. + items: + type: string + example: + delete_all: false + emails: + - example1@example.com + - example2@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '204': description: '' schema: type: object + properties: {} security: - Authorization: [] - '/templates/{template_id}/versions': + '/suppression/blocks/{email}': parameters: - - name: template_id + - name: email in: path + description: The email address of the specific block. required: true type: string - post: - operationId: POST_templates-template_id-versions - summary: Create a new transactional template version. + format: email + get: + operationId: GET_suppression-blocks-email + summary: Retrieve a specific block tags: - - Transactional Templates Versions - 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). - consumes: - - application/json - produces: - - application/json + - Blocks API + description: '**This endpoint allows you to retrieve a specific email address from your blocks list.**' parameters: - - name: body - in: body + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' schema: - $ref: '#/definitions/transactional_template_version' - example: - template_id: ddb96bbc-9b92-425e-8979-99464621b543 - active: 1 - name: example_version_name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> + $ref: '#/definitions/blocks-response' + examples: + application/json: + - created: 1443651154 + email: example@example.com + reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' + status: 4.0.0 + security: + - Authorization: [] + delete: + operationId: DELETE_suppression-blocks-email + summary: Delete a specific block + tags: + - Blocks API + description: '**This endpoint allows you to delete a specific email address from your blocks list.**' + parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '201': + '204': 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 + properties: {} + security: + - Authorization: [] + /suppression/spam_reports: + get: + operationId: GET_suppression-spam_reports + summary: Retrieve all spam reports + tags: + - Spam Reports API + description: '**This endpoint allows you to retrieve all spam reports.**' + parameters: + - name: start_time + in: query + description: The start of the time range when a spam report was created (inclusive). This is a unix timestamp. + type: integer + - name: end_time + in: query + description: The end of the time range when a spam report was created (inclusive). This is a unix timestamp. + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: Paging offset. The point in the list to begin displaying results. + type: integer + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/spam-reports-response' 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' + - created: 1443651141 + email: user1@example.com + ip: 10.63.202.100 + - created: 1443651154 + email: user2@example.com + ip: 10.63.202.100 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: - operationId: POST_templates-template_id-versions-version_id-activate - summary: Activate a transactional template version. + delete: + operationId: DELETE_suppression-spam_reports + summary: Delete spam reports tags: - - Transactional Templates Versions + - Spam Reports API 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. + **This endpoint allows you to delete your spam reports.** + Deleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required. - For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + There are two options for deleting spam reports: - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | template_id | string | The ID of the original template | - | version_id | string | The ID of the template version | - produces: - - application/json + 1. You can delete all spam reports by setting the `delete_all` field to `true` in the request body. + 2. You can delete a list of select spam reports by specifying the email addresses in the `emails` array of the request body. parameters: - name: body in: body schema: - type: 'null' + type: object + properties: + delete_all: + type: boolean + description: Indicates if you want to delete all email addresses on the spam report list. + emails: + type: array + description: A list of specific email addresses that you want to remove from the spam report list. + items: + type: string + example: + delete_all: false + emails: + - example1@example.com + - example2@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': 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' + properties: {} security: - Authorization: [] - '/templates/{template_id}/versions/{version_id}': + '/suppression/spam_reports/{email}': parameters: - - name: template_id - in: path - required: true - type: string - - name: version_id + - name: email in: path + description: The email address of a specific spam report that you want to retrieve. required: true type: string + format: email get: - operationId: GET_templates-template_id-versions-version_id - summary: Retrieve a specific transactional template version. + operationId: GET_suppression-spam_reports-email + summary: Retrieve a specific spam report tags: - - Transactional Templates Versions - 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 | - produces: - - application/json + - Spam Reports API + description: '**This endpoint allows you to retrieve a specific spam report by email address.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - id: - type: string - description: The ID of the template version. - updated_at: - type: string - description: The date and time that the template version was last updated. - Transactional Template Version: - $ref: '#/definitions/transactional_template_version' - required: - - id - - updated_at + $ref: '#/definitions/spam-reports-response' 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' + - created: 1454433146 + email: test1@example.com + ip: 10.89.32.5 security: - Authorization: [] - patch: - operationId: PATCH_templates-template_id-versions-version_id - summary: Edit a transactional template version. + delete: + operationId: DELETE_suppression-spam_reports-email + summary: Delete a specific spam report tags: - - Transactional Templates Versions + - Spam Reports API 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. + **This endpoint allows you to delete a specific spam report by email address.** - 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 | - consumes: - - application/json - produces: - - application/json + Deleting a spam report will remove the suppression, meaning email will once again be sent to the previously suppressed address. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + properties: {} + security: + - Authorization: [] + /asm/suppressions/global: + post: + operationId: POST_asm-suppressions-global + summary: Add recipient addresses to the global suppression group. + tags: + - Suppressions - Global Suppressions + description: '**This endpoint allows you to add one or more email addresses to the global suppressions group.**' 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. + $ref: '#/definitions/suppressions-request' example: - active: 1 - name: updated_example_name - html_content: <%body%> - plain_content: <%body%> - subject: <%subject%> + recipient_emails: + - test1@example.com + - test2@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '201': 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' + recipient_emails: + type: array + description: The email addresses that are globally suppressed + items: + type: string + format: email required: - - id - - updated_at + - recipient_emails 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' + recipient_emails: + - test1@example.com + - test2@example.com security: - Authorization: [] - delete: - operationId: DELETE_templates-template_id-versions-version_id - summary: Delete a transactional template version. + /suppression/unsubscribes: + get: + operationId: GET_suppression-unsubscribes + summary: Retrieve all global suppressions tags: - - Transactional Templates Versions - 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 | + - Suppressions - Global Suppressions + description: '**This endpoint allows you to retrieve a list of all email address that are globally suppressed.**' parameters: - - name: body - in: body - schema: - type: 'null' + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive). + type: integer + - name: limit + in: query + description: The number of results to display on each page. + type: integer + - name: offset + in: query + description: The point in the list of results to begin displaying global suppressions. + type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '204': + '200': description: '' schema: - type: 'null' + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the recipient was added to the global suppression list. + email: + type: string + description: The email address of the recipient who is globally suppressed. + format: email + required: + - created + - email + examples: + application/json: + - created: 1443651141 + email: user1@example.com + - created: 1443651154 + email: user2@example.com security: - Authorization: [] - /user/profile: + '/asm/suppressions/global/{email}': + parameters: + - name: email + in: path + description: 'The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.' + required: true + type: string get: - operationId: GET_user-profile - summary: Get a user's profile + operationId: GET_asm-suppressions-global-email + summary: Retrieve a Global Suppression tags: - - Users API + - Suppressions - Global Suppressions 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: + **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.** - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - produces: - - application/json + If the email address you include in the URL path parameter `{email}` is already globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - title: GET User Profile response + title: Retrieve a Global Suppression 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: + recipient_email: type: string - description: The user's zip code. + description: The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed. + format: email required: - - address - - city - - company - - country - - first_name - - last_name - - phone - - state - - website - - zip + - recipient_email 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' + recipient_email: test@example.com security: - Authorization: [] - patch: - operationId: PATCH_user-profile - summary: Update a user's profile + delete: + operationId: DELETE_asm-suppressions-global-email + summary: Delete a Global Suppression tags: - - Users API + - Suppressions - Global Suppressions description: |- - **This endpoint allows you to update your current profile details.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: + **This endpoint allows you to remove an email address from the global suppressions group.** - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + Deleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + security: + - Authorization: [] + /asm/groups: + post: + operationId: POST_asm-groups + summary: Create a new suppression group + tags: + - Suppressions - Unsubscribe Groups + description: |- + **This endpoint allows you to create a new suppression group.** - 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. - consumes: - - application/json - produces: - - application/json + To add an email address to the suppression group, [create a Suppression](https://sendgrid.api-docs.io/v3.0/suppressions-suppressions/add-suppressions-to-a-suppression-group). parameters: - name: body in: body schema: - $ref: '#/definitions/user_profile' + $ref: '#/definitions/suppression-group-request-base' example: - first_name: Example - last_name: User - city: Orange + name: Product Suggestions + description: Suggestions for products our users might like. + is_default: true - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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': + '201': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + id: + type: integer + description: The ID of the suppression group. + name: + type: string + description: The name of the suppression group. + description: + type: string + description: A brief description of the suppression group. + is_default: + type: boolean + description: Indicates if this is the default suppression group. + required: + - id + - name + - description + - is_default examples: application/json: - errors: - - field: null - message: authorization required + id: 103 + name: Product Suggestions + description: Suggestions for products our users might like. + is_default: false security: - Authorization: [] - /user/account: get: - operationId: GET_user-account - summary: Get a user's account information. + operationId: GET_asm-groups + summary: Retrieve all suppression groups associated with the user. tags: - - Users API + - Suppressions - Unsubscribe Groups description: |- - **This endpoint allows you to retrieve your user account details.** + **This endpoint allows you to retrieve a list of all suppression groups created by this user.** - Your user's account information includes the user's account type and reputation. - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: - - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - produces: - - application/json + This endpoint can also return information for multiple group IDs that you include in your request. To add a group ID to your request, simply append `?id=123456&id=123456`, with the appropriate group IDs. parameters: + - name: id + in: query + type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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 + type: array + items: + $ref: '#/definitions/suppression_group' examples: application/json: - reputation: 100 - type: paid + - 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 security: - Authorization: [] - /user/email: + '/asm/groups/{group_id}': + parameters: + - name: group_id + in: path + description: The ID of the suppression group you would like to retrieve. + required: true + type: string get: - operationId: GET_user-email - summary: Retrieve your account email address + operationId: GET_asm-groups-group_id + summary: Get information on a single suppression group. tags: - - Users API - description: |- - **This endpoint allows you to retrieve the email address currently on file for your account.** - - 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) - produces: - - application/json + - Suppressions - Unsubscribe Groups + description: '**This endpoint allows you to retrieve a single suppression group.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - email: - type: string - description: The email address currently on file for your account. - required: - - email + allOf: + - $ref: '#/definitions/suppression-group-request-base' + - type: object + properties: + id: + type: integer + description: The ID of the suppression group. + unsubscribes: + type: integer + description: 'The number of unsubscribes, or suppressions, in this group.' + last_email_sent_at: + type: + - string + - 'null' + required: + - id examples: application/json: - email: test@example.com + description: Our monthly newsletter. + id: 100 + is_default: true + last_email_sent_at: null + name: Newsletters + unsubscribes: 400 security: - Authorization: [] - put: - operationId: PUT_user-email - summary: Update your account email address + patch: + operationId: PATCH_asm-groups-group_id + summary: Update a suppression group. tags: - - Users API - description: |- - **This endpoint allows you to update the email address currently on file for your account.** - - 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) - consumes: - - application/json - produces: - - application/json + - Suppressions - Unsubscribe Groups + description: '**This endpoint allows you to update or change a suppression group.**' parameters: - name: body in: body schema: - type: object - properties: - email: - type: string - description: The new email address that you would like to use for your account. + allOf: + - $ref: '#/definitions/suppression-group-request-base' example: - email: example@example.com + id: 103 + name: Item Suggestions + description: Suggestions for items our users might like. - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '201': description: '' schema: - type: object - properties: - email: - type: string - description: The current email address on file for your account. - required: - - email + $ref: '#/definitions/suppression_group' + examples: + application/json: + id: 103 + name: Item Suggestions + description: Suggestions for items our users might like. security: - Authorization: [] - /user/username: - get: - operationId: GET_user-username - summary: Retrieve your username + delete: + operationId: DELETE_asm-groups-group_id + summary: Delete a Suppression Group tags: - - Users API + - Suppressions - Unsubscribe Groups description: |- - **This endpoint allows you to retrieve your current account username.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + **This endpoint allows you to delete a suppression group.** - For more information about your user profile: + 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. - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - produces: - - application/json + Deleting a suppression group will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required. parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '204': description: '' schema: type: object - properties: - username: - type: string - description: Your account username. - user_id: - type: integer - description: The user ID for your account. - required: - - username - - user_id - examples: - application/json: - username: test_username - user_id: 1 security: - Authorization: [] - put: - operationId: PUT_user-username - summary: Update your username + '/asm/groups/{group_id}/suppressions': + parameters: + - name: group_id + in: path + description: The id of the unsubscribe group that you are adding suppressions to. + required: true + type: string + post: + operationId: POST_asm-groups-group_id-suppressions + summary: Add suppressions to a suppression group tags: - - Users API + - Suppressions - Suppressions description: |- - **This endpoint allows you to update the username for your account.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: + **This endpoint allows you to add email addresses to an unsubscribe group.** - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - consumes: - - application/json - produces: - - application/json + 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. parameters: - name: body in: body schema: - type: object - properties: - username: - type: string - description: The new username you would like to use for your account. + $ref: '#/definitions/suppressions-request' example: - username: test_username + recipient_emails: + - test1@example.com + - test2@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: - '200': + '201': description: '' schema: type: object properties: - username: - type: string - description: The current username on file for your account. - required: - - username + recipient_emails: + type: array + description: The email addresses you added to the unsubscribe group + items: + type: string + format: email examples: application/json: - username: test_username + recipient_emails: + - test1@example.com + - test2@example.com security: - Authorization: [] - /user/credits: get: - operationId: GET_user-credits - summary: Retrieve your credit balance + operationId: GET_asm-groups-group_id-suppressions + summary: Retrieve all suppressions for a suppression group tags: - - Users API - description: |- - **This endpoint allows you to retrieve the current credit balance for your account.** - - Your monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html). - produces: - - application/json + - Suppressions - Suppressions + description: '**This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: - remain: - type: integer - description: The remaining number of credits available on your account. - total: - type: integer - description: The total number of credits assigned to your account. - overage: - type: integer - description: The number of overdrawn credits for your account. - used: - type: integer - description: The number of credits that you have used. - last_reset: - type: string - description: The date that your credit balance was last reset. - next_reset: - type: string - description: The next date that your credit balance will be reset. - reset_frequency: - type: string - description: The frequency at which your credit balance will be reset. - required: - - remain - - total - - overage - - used - - last_reset - - next_reset - - reset_frequency + type: array + description: The list of email addresses belonging to the given suppression group. + items: + type: string + format: email examples: application/json: - remain: 200 - total: 200 - overage: 0 - used: 0 - last_reset: '2013-01-01' - next_reset: '2013-02-01' - reset_frequency: monthly + - example@example.com + - example2@example.com security: - Authorization: [] - /user/password: - put: - operationId: PUT_user-password - summary: Update your password + '/asm/groups/{group_id}/suppressions/search': + parameters: + - name: group_id + in: path + description: The ID of the suppression group that you would like to search. + required: true + type: string + post: + operationId: POST_asm-groups-group_id-suppressions-search + summary: Search for suppressions within a group tags: - - Users API + - Suppressions - Suppressions description: |- - **This endpoint allows you to update your password.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: + **This endpoint allows you to search a suppression group for multiple suppressions.** - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - produces: - - application/json + When given a list of email addresses and a group ID, this endpoint will only return the email addresses that have been unsubscribed from the given group. parameters: - name: body in: body schema: - type: object - properties: - new_password: - type: string - description: The new password you would like to use for your account. - old_password: - type: string - description: The old password for your account. - required: - - new_password - - old_password + $ref: '#/definitions/suppressions-request' example: - new_password: new_password - old_password: old_password + recipient_emails: + - exists1@example.com + - exists2@example.com + - doesnotexists@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - type: object - properties: {} + type: array + description: The email address from your search that do exist in the suppression group. + items: + type: string + format: email + examples: + application/json: + - exists1@example.com + - exists2@example.com security: - Authorization: [] - /user/webhooks/event/settings: + /asm/suppressions: get: - operationId: GET_user-webhooks-event-settings - summary: Retrieve Event Webhook settings + operationId: GET_asm-suppressions + summary: Retrieve all suppressions tags: - - Webhooks - description: |- - **This endpoint allows you to retrieve your current event webhook settings.** - - If an event type is marked as `true`, then the event webhook will include information about that event. - - SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - - Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - produces: - - application/json + - Suppressions - Suppressions + description: '**This endpoint allows you to retrieve a list of all suppressions.**' parameters: - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/event_webhook_settings' + type: array + items: + type: object + properties: + email: + type: string + description: The email address that was suppressed. + group_id: + type: integer + description: The id of the suppression group that this email address belongs to. + group_name: + type: string + description: The name of the suppression group that this email address belongs to. + created_at: + type: integer + description: A UNIX timestamp indicating when the suppression was created. + required: + - email + - group_id + - group_name + - created_at examples: application/json: - 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 + - email: test1@example.com + group_id: 1 + group_name: Weekly News + created_at: 1410986704 + - email: test1@example.com + group_id: 2 + group_name: Daily News + created_at: 1411493671 + - email: test2@example.com + group_id: 2 + group_name: Daily News + created_at: 1411493671 security: - Authorization: [] - patch: - operationId: PATCH_user-webhooks-event-settings - summary: Update Event Notification Settings + '/asm/suppressions/{email}': + parameters: + - name: email + in: path + description: The email address that you want to search suppression groups for. + required: true + type: string + get: + operationId: GET_asm-suppressions-email + summary: Retrieve all suppression groups for an email address tags: - - Webhooks + - Suppressions - Suppressions + description: '**This endpoint returns a list of all groups from which the given email address has been unsubscribed.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + type: object + properties: + suppressions: + type: array + description: The array of suppression groups. + items: + type: object + properties: + description: + type: string + description: The description of the suppression group. + id: + type: integer + description: The id of the suppression group. + is_default: + type: boolean + description: Indicates if the suppression group is set as the default. + name: + type: string + description: The name of the suppression group. + suppressed: + type: boolean + description: Indicates if the given email address is suppressed for this group. + required: + - description + - id + - is_default + - name + - suppressed + required: + - suppressions + examples: + application/json: + suppressions: + - description: Optional description. + id: 1 + is_default: true + name: Weekly News + suppressed: true + - description: Some daily news. + id: 2 + is_default: true + name: Daily News + suppressed: true + - description: An old group. + id: 2 + is_default: false + name: Old News + suppressed: false + security: + - Authorization: [] + '/asm/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: + operationId: DELETE_asm-groups-group_id-suppressions-email + summary: Delete a suppression from a suppression group + tags: + - Suppressions - Suppressions description: |- - **This endpoint allows you to update your current event webhook settings.** - - If an event type is marked as `true`, then the event webhook will include information about that event. - - SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + **This endpoint allows you to remove a suppressed email address from the given suppression group.** - Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - consumes: - - application/json - produces: - - application/json + Removing an address will remove the suppression, meaning email will once again be sent to the previously suppressed addresses. This should be avoided unless a recipient indicates they wish to receive email from you again. You can use our [bypass filters](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#bypass-suppressions) to deliver messages to otherwise suppressed addresses when exceptions are required. parameters: - - name: body - in: body + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' schema: - $ref: '#/definitions/event_webhook_settings' - example: - enabled: true - url: url - group_resubscribe: true - delivered: true - group_unsubscribe: true - spam_report: true - bounce: true - deferred: true - unsubscribe: true - processed: true - open: true - click: true - dropped: true + type: 'null' + security: + - Authorization: [] + /suppression/invalid_emails: + get: + operationId: GET_suppression-invalid_emails + summary: Retrieve all invalid emails + tags: + - Invalid Emails API + description: '**This endpoint allows you to retrieve a list of all invalid email addresses.**' + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when an invalid email was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when an invalid email was created (inclusive). + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: Paging offset. The point in the list to begin displaying results. + type: integer - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '200': description: '' schema: - $ref: '#/definitions/event_webhook_settings' + type: array + description: The list of invalid email addresses. + items: + $ref: '#/definitions/invalid-email' 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 + - created: 1449953655 + email: user1@example.com + reason: Mail domain mentioned in email address is unknown + - created: 1449939373 + email: user2@example.com + reason: Mail domain mentioned in email address is unknown security: - Authorization: [] - /user/webhooks/event/test: - post: - operationId: POST_user-webhooks-event-test - summary: Test Event Notification Settings + delete: + operationId: DELETE_suppression-invalid_emails + summary: Delete invalid emails tags: - - Webhooks + - Invalid Emails API description: |- - **This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** + **This endpoint allows you to remove email addresses from your invalid email address list.** - SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + There are two options for deleting invalid email addresses: - Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - produces: - - application/json + 1) You can delete all invalid email addresses by setting `delete_all` to true in the request body. + 2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. parameters: - name: body in: body schema: type: object properties: - url: - type: string - description: The URL where you would like the test notification to be sent. + delete_all: + type: boolean + description: Indicates if you want to remove all email address from the invalid emails list. + emails: + type: array + description: The list of specific email addresses that you want to remove. + items: + type: string + format: email example: - url: url + delete_all: false + emails: + - example1@example.com + - example2@example.com - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' responses: '204': description: '' schema: type: object + properties: {} security: - Authorization: [] - /user/webhooks/parse/stats: + '/suppression/invalid_emails/{email}': + parameters: + - name: email + in: path + description: The specific email address of the invalid email entry that you want to retrieve. + required: true + type: string get: - operationId: GET_user-webhooks-parse-stats - summary: Retrieves Inbound Parse Webhook statistics. + operationId: GET_suppression-invalid_emails-email + summary: Retrieve a specific invalid email tags: - - Webhooks - 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). - produces: - - application/json + - Invalid Emails API + description: '**This endpoint allows you to retrieve a specific invalid email addresses.**' parameters: - - name: limit - in: query - description: The number of statistics to return on each page. - required: false - type: string - - name: offset - in: query - description: The number of statistics to skip. - required: false - type: string - - name: aggregated_by - in: query - description: 'How you would like the statistics to by grouped. ' - required: false - type: string - enum: - - day - - week - - month - - name: start_date - in: query - description: The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD - required: true - type: string - - name: end_date - in: query - description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD - required: false - type: string - default: The day the request is made. - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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 + description: '' + schema: + type: array + description: A specific invalid email. + minItems: 0 + maxItems: 1 + items: + $ref: '#/definitions/invalid-email' + examples: + application/json: + - created: 1454433146 + email: test1@example.com + reason: Mail domain mentioned in email address is unknown security: - Authorization: [] - /whitelabel/domains: + delete: + operationId: DELETE_suppression-invalid_emails-email + summary: Delete a specific invalid email + tags: + - Invalid Emails API + description: '**This endpoint allows you to remove a specific email address from the invalid email address list.**' + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + properties: {} + security: + - Authorization: [] + '/user/webhooks/parse/settings/{hostname}': + parameters: + - name: hostname + in: path + description: The hostname associated with the inbound parse setting that you would like to retrieve. + required: true + type: string get: - operationId: GET_whitelabel-domains - summary: List all domain whitelabels. + operationId: GET_user-webhooks-parse-settings-hostname + summary: Retrieve a specific parse setting tags: - - Whitelabel - Domains + - Settings - Inbound Parse description: |- - **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** + **This endpoint allows you to retrieve a specific inbound parse setting by hostname.** - 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) - produces: - - application/json + You can retrieve all your Inbound Parse settings and their associated host names with the #endpoint:b8xyiHYsGatArCnSt endpoint. 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 - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' 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 + $ref: '#/definitions/parse-setting' 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 + url: 'http://mydomain.com/parse' + hostname: mail.mydomain.com + spam_check: true + send_raw: true + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' security: - Authorization: [] - post: - operationId: POST_whitelabel-domains - summary: Create a domain whitelabel. + patch: + operationId: PATCH_user-webhooks-parse-settings-hostname + summary: Update a parse setting tags: - - Whitelabel - Domains + - Settings - Inbound Parse 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. + **This endpoint allows you to update a specific inbound parse setting by hostname.** - 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) - consumes: - - application/json - produces: - - application/json + You can retrieve all your Inbound Parse settings and their associated host names with the #endpoint:b8xyiHYsGatArCnSt endpoint. parameters: - name: body in: body schema: + $ref: '#/definitions/parse-setting' + example: + url: 'http://newdomain.com/parse' + spam_check: false + send_raw: true + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '200': + description: '' + schema: + $ref: '#/definitions/parse-setting' + examples: + application/json: + url: 'http://mydomain.com/parse' + hostname: mail.mydomain.com + spam_check: true + send_raw: true + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] + delete: + operationId: DELETE_user-webhooks-parse-settings-hostname + summary: Delete a parse setting + tags: + - Settings - Inbound Parse + description: |- + **This endpoint allows you to delete a specific inbound parse setting by hostname.** + + You can retrieve all your Inbound Parse settings and their associated host names with the #endpoint:b8xyiHYsGatArCnSt endpoint. + parameters: + - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' + responses: + '204': + description: '' + schema: + type: object + '401': + $ref: '#/responses/trait:globalErrors:401' + '403': + $ref: '#/responses/trait:globalErrors:403' + '404': + $ref: '#/responses/trait:globalErrors:404' + '500': + $ref: '#/responses/trait:globalErrors:500' + security: + - Authorization: [] +parameters: + 'trait:onBehalfOfSubuser:on-behalf-of': + name: on-behalf-of + in: header + type: string + default: The subuser's username. This header generates the API call as if the subuser account was making the call. + 'trait:baseParams:aggregated_by': + name: aggregated_by + in: query + description: 'Dictates how the stats are time-sliced. Currently, `"total"` and `"day"` are supported.' + type: string + default: total + enum: + - day + - total + 'trait:baseParams:start_date': + name: start_date + in: query + description: 'Format: `YYYY-MM-DD`. If this parameter is included, the stats'' start date is included in the search.' + type: string + format: date + default: '' + 'trait:baseParams:end_date': + name: end_date + in: query + description: 'Format: `YYYY-MM-DD`.If this parameter is included, the stats'' end date is included in the search.' + type: string + default: '' + format: date + 'trait:baseParams:timezone': + name: timezone + in: query + description: '[IANA Area/Region](https://en.wikipedia.org/wiki/Tz_database#Names_of_time_zones) string representing the timezone in which the stats are to be presented, e.g., "America/Chicago".' + type: string + default: UTC + 'trait:pagination:page_size': + name: page_size + in: query + description: The number of elements you want returned on each page. + type: integer + default: 50 + minimum: 1 + maximum: 100 + 'trait:pagination:page_token': + name: page_token + in: query + description: 'The stats endpoints are paginated. To get the next page, call the passed `_metadata.next` URL. If `_metadata.prev` doesn''t exist, you''re at the first page. Similarly, if `_metadata.next` is not present, you''re at the last page.' + type: string + 'trait:singlesendQueryParams:group_by': + name: group_by + in: query + description: A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields. + type: array + enum: + - ab_variation + - ab_phase + items: + type: string + 'trait:automationQueryParams:group_by': + name: group_by + in: query + description: Automations can have multiple steps. Including `step_id` as a `group_by` metric allows further granularity of stats. + type: array + enum: + - step_id + items: + type: string + 'trait:automationQueryParams:step_ids': + name: step_ids + in: query + description: Comma-separated list of `step_ids` that you want the link stats for. + type: array + uniqueItems: true + items: + type: string + format: uuid + 'trait:singlesendQueryParams2:group_by': + name: group_by + in: query + description: A/B Single Sends have multiple variation IDs and phase IDs. Including these additional fields allows further granularity of stats by these fields. + type: array + enum: + - ab_variation + - ab_phase + items: + type: string + 'trait:singlesendQueryParams2:ab_variation_id': + name: ab_variation_id + in: query + type: string + format: uuid + 'trait:singlesendQueryParams2:ab_phase_id': + name: ab_phase_id + in: query + type: string + enum: + - test + - send + 'trait:statsAdvancedStatsBaseQueryStrings:start_date': + name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + 'trait:statsAdvancedStatsBaseQueryStrings:end_date': + 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 + 'trait:statsAdvancedStatsBaseQueryStrings:aggregated_by': + 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 + 'trait:statsAdvancedQueryStringsLimitOffset:limit': + name: limit + in: query + description: The number of results to return. + required: false + type: integer + 'trait:statsAdvancedQueryStringsLimitOffset:offset': + name: offset + in: query + description: The point in the list to begin retrieving results. + required: false + type: integer + 'trait:statsAdvancedQueryStringsLimitOffset:aggregated_by': + 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 + 'trait:statsAdvancedQueryStringsLimitOffset:start_date': + name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + 'trait:statsAdvancedQueryStringsLimitOffset:end_date': + 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 + 'trait:designsQueryStrings:page_size': + name: page_size + in: query + description: number of results to return + type: integer + minimum: 0 + default: 100 + 'trait:designsQueryStrings:page_token': + name: page_token + in: query + description: 'token corresponding to a specific page of results, as provided by metadata' + type: string + 'trait:designsQueryStrings:summary': + name: summary + in: query + description: set to false to return all fields + type: boolean + default: 'true' + 'trait:authorizationHeader:Authorization': + name: Authorization + in: header + required: true + type: string + default: Bearer <> +responses: + 'trait:errorResponse:400': + description: '' + schema: + $ref: '#/definitions/error_schema' + 'trait:pagination:200': + description: '' + schema: + type: object + properties: + _metadata: + $ref: '#/definitions/metadata' + 'trait:mailSendErrors:400': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:mailSendErrors:413': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:globalErrors:401': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:globalErrors:403': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:globalErrors:404': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:globalErrors:500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: type: object properties: - domain: + message: type: string - description: Domain being whitelabeled. - subdomain: + 'trait:cancelScheduledSendsErrors:400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: type: string - description: The subdomain to use for this domain whitelabel. - username: + field: + type: string + help: + type: object + id: + type: string + 'trait:apiKeysErrors:400': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:apiKeysErrors:403': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:apiKeysErrors:404': + description: '' + schema: + $ref: '#/definitions/global_error_response_schema' + 'trait:makoErrorResponse:400': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + error_id: + type: string + description: The ID associated with the error. + field: + type: + - string + - 'null' + description: The field that generated the error. + message: + type: string + description: The error message. + parameter: type: string - description: The username that this whitelabel will be associated with. - ips: - type: array - description: The IP addresses that will be included in the custom SPF record for this whitelabel. - items: - type: string - custom_spf: - type: boolean - description: Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security. - default: - type: boolean - description: Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain. - automatic_security: - type: boolean - description: 'Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.' required: - - domain - - subdomain - example: - domain: example.com - subdomain: news - username: john@example.com - ips: - - 192.168.1.1 - - 192.168.1.2 - custom_spf: true - default: true - automatic_security: false - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '201': - description: '' - schema: - $ref: '#/definitions/whitelabel::domain' - examples: - application/json: - id: 302183 - user_id: 1446226 - subdomain: example - domain: example.com - username: mbernier - ips: [] - custom_spf: false - default: true - legacy: false - automatic_security: true - valid: false - dns: - mail_cname: - valid: false - type: cname - host: example.example.com - data: u1446226.wl.sendgrid.net - dkim1: - valid: false - type: cname - host: s1._domainkey.example.com - data: s1.domainkey.u1446226.wl.sendgrid.net - dkim2: - valid: false - type: cname - host: s2._domainkey.example.com - data: s2.domainkey.u1446226.wl.sendgrid.net - security: - - Authorization: [] - '/whitelabel/domains/{domain_id}': - parameters: - - name: domain_id - in: path - required: true + - message + 'trait:makoErrorResponse:401': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + error_id: + type: string + description: The ID associated with the error. + field: + type: + - string + - 'null' + description: The field that generated the error. + message: + type: string + description: The error message. + parameter: + type: string + required: + - message + 'trait:makoErrorResponse:403': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + error_id: + type: string + description: The ID associated with the error. + field: + type: + - string + - 'null' + description: The field that generated the error. + message: + type: string + description: The error message. + parameter: + type: string + required: + - message + 'trait:makoErrorResponse:404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + error_id: + type: string + description: The ID associated with the error. + field: + type: + - string + - 'null' + description: The field that generated the error. + message: + type: string + description: The error message. + parameter: + type: string + required: + - message + 'trait:makoErrorResponse:500': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + error_id: + type: string + description: The ID associated with the error. + field: + type: + - string + - 'null' + description: The field that generated the error. + message: + type: string + description: The error message. + parameter: + type: string + required: + - message + 'trait:singleSignOnErrorsTrait:400': + description: '' + schema: + $ref: '#/definitions/sso-error-response' + 'trait:singleSignOnErrorsTrait:401': + description: '' + schema: + $ref: '#/definitions/sso-error-response' + 'trait:singleSignOnErrorsTrait:403': + description: '' + schema: + $ref: '#/definitions/sso-error-response' + 'trait:singleSignOnErrorsTrait:429': + description: '' + schema: + $ref: '#/definitions/sso-error-response' + 'trait:singleSignOnErrorsTrait:500': + description: '' + schema: + $ref: '#/definitions/sso-error-response' +definitions: + partner_settings_new_relic: + title: '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 + subscription_tracking_settings: + title: 'Settings: Subscription Tracking' + 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. + format: uri + contactdb_recipient_response: + 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 + example: + error_count: 1 + error_indices: + - 2 + new_count: 2 + persisted_recipients: + - YUBh + - bWlsbGVyQG1pbGxlci50ZXN0 + updated_count: 0 + errors: + - message: Invalid email. + error_indices: + - 2 + campaign_response: + title: Campaigns 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_conditions: + title: 'ContactDB: Segments: Conditions' + type: object + properties: + field: type: string - get: - operationId: GET_whitelabel-domains-domain_id - summary: Retrieve a domain whitelabel. - tags: - - Whitelabel - Domains - 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) - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - $ref: '#/definitions/whitelabel::domain' - security: - - Authorization: [] - patch: - operationId: PATCH_whitelabel-domains-domain_id - summary: Update a domain whitelabel. - tags: - - Whitelabel - Domains - 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) - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - default: - type: boolean - default: false - description: Indicates whether this domain whitelabel should be considered the default. - custom_spf: - type: boolean - default: false - description: Indicates whether to generate a custom SPF record for manual security. - example: - default: false - custom_spf: true - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - delete: - operationId: DELETE_whitelabel-domains-domain_id - summary: Delete a domain whitelabel. - tags: - - Whitelabel - Domains - 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) - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - security: - - Authorization: [] - /whitelabel/domains/default: - get: - operationId: GET_whitelabel-domains-default - summary: Get the default domain whitelabel. - tags: - - Whitelabel - Domains - 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. | - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - $ref: '#/definitions/whitelabel:domain_spf' - security: - - Authorization: [] - '/whitelabel/domains/{id}/ips': - parameters: - - name: id - in: path - required: true + value: + type: string + operator: + type: string + enum: + - eq + - ne + - lt + - gt + - contains + and_or: + type: string + enum: + - and + - or + - '' + required: + - field + - value + - operator + bounce_response: + title: Bounce Response + type: object + properties: + created: + type: number + description: The unix timestamp for when the bounce record was created at SendGrid. + email: + type: string + format: email + description: The email address that was added to the bounce list. + 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 + 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 + contacts: + title: Contacts + type: object + properties: + address: + type: string + address2: + type: object + 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 + reverse_dns: + title: Reverse DNS + type: object + properties: + id: + type: integer + description: The ID of the Reverse DNS. + ip: + type: string + description: The IP address that this Reverse DNS was created for. + rdns: + type: string + description: The reverse DNS record for the IP address. This points to the Reverse DNS subdomain. + users: + type: array + description: The users who are able to send mail from the IP address. + items: + type: object + properties: + username: + type: string + description: The username of a user who can send mail from the IP address. + user_id: + type: integer + description: The ID of a user who can send mail from the IP address. + required: + - username + - user_id + subdomain: + type: string + description: The subdomain created for this reverse DNS. 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 Reverse DNS. + legacy: + type: boolean + description: 'Indicates if this Reverse DNS was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you''ll need to create a new Reverse DNS if you need to update it.' + last_validation_attempt_at: + type: integer + description: A Unix epoch timestamp representing the last time of a validation attempt. + 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 set up with Reverse DNS. + required: + - id + - ip + - rdns + - users + - domain + - valid + - legacy + - a_record + 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 + senderID: + title: Sender ID + type: object + properties: + id: + type: integer + description: The unique identifier of the sender identity. + nickname: type: string - post: - operationId: POST_whitelabel-domains-id-ips - summary: Add an IP to a domain whitelabel. - tags: - - Whitelabel - Domains - 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 | - 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 - example: - ip: 192.168.0.1 - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - '/whitelabel/domains/{id}/ips/{ip}': - parameters: - - name: id - in: path - required: true + description: A nickname for the sender identity. Not used for sending. + from: + type: object + properties: + email: + type: string + description: This is where the email will appear to originate from for your recipient + name: + type: string + description: This is the name appended to the from email field. IE - Your name or company name. + required: + - email + reply_to: + type: object + properties: + email: + type: string + description: This is the email that your recipient will reply to. + name: + type: string + description: This is the name appended to the reply to email field. IE - Your name or company name. + address: type: string - - name: ip - in: path - required: true + description: The physical address of the sender identity. + address_2: type: string - delete: - operationId: DELETE_whitelabel-domains-id-ips-ip - summary: Remove an IP from a domain whitelabel. - tags: - - Whitelabel - Domains - 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. | - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - '/whitelabel/domains/{id}/validate': - parameters: - - name: id - in: path - required: true + description: Additional sender identity address information. + city: type: string - post: - operationId: POST_whitelabel-domains-id-validate - summary: Validate a domain whitelabel. - tags: - - Whitelabel - Domains - 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. | - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: + description: The city of the sender identity. + state: + type: string + description: The state of the sender identity. + zip: + type: string + description: The zipcode of the sender identity. + country: + type: string + description: The country of the sender identity. + verified: + type: boolean + description: If the sender identity is verified or not. Only verified sender identities can be used to send email. + updated_at: + type: integer + description: The time the sender identity was last updated. + created_at: + type: integer + description: The time the sender identity was created. + locked: + type: boolean + description: 'A sender identity is locked when it is associated to a campaign in the Draft, Scheduled, or In Progress status. You cannot update or delete a locked sender identity.' + required: + - nickname + - address + - city + - country + example: + id: 1 + nickname: My Sender ID + from: + email: from@example.com + name: Example INC + reply_to: + email: replyto@example.com + name: Example INC + address: 123 Elm St. + address_2: Apt. 456 + city: Denver + state: Colorado + zip: '80202' + country: United States + verified: true + updated_at: 1449872165 + created_at: 1449872165 + locked: false + 'global:empty_request': + title: 'Global: Request Empty Body' + type: 'null' + 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 + example: + name: first_name + type: text + 'domain_authentication:domain_spf': + title: Domain Authentication + type: object + properties: + id: + type: integer + description: The ID of the authenticated domain. + domain: + type: string + description: The domain authenticated. + subdomain: + type: string + description: The subdomain that was used to create this authenticated domain. + username: + type: string + description: The username of the account that this authenticated domain is associated with. + user_id: + type: integer + description: The user_id of the account that this authenticated domain is associated with. + ips: + type: array + description: The IP addresses that are included in the SPF record for this authenticated domain. + items: {} + custom_spf: + type: boolean + description: Indicates if this authenticated domain uses custom SPF. + default: + type: boolean + description: Indicates if this is the default domain. + legacy: + type: boolean + description: 'Indicates if this authenticated domain was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you''ll need to create a new authenticated domain if you need to update it.' + automatic_security: + type: boolean + description: Indicates if this authenticated domain uses automated security. + valid: + type: boolean + description: Indicates if this is a valid authenticated domain . + dns: + type: object + description: The DNS records for this authenticated domain. + 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: - id: - type: integer - description: The ID of the domain whitelabel. + 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 whitelabel. - validation_results: - 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_results: - mail_cname: - valid: false - reason: Expected your MX record to be "mx.sendgrid.net" but found "example.com". - dkim1: - valid: true - reason: null - dkim2: - valid: true - reason: null - spf: - valid: true - reason: null - '500': - description: '' - schema: + description: Indicates if this is a valid DNS record. + subdomain_spf: type: object + description: The SPF record for the subdomain used to create this authenticated domain. + required: + - host + - type + - data + - valid properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - description: A message explaining the reason for the error. - required: - - message - examples: - application/json: - errors: - - message: internal error getting TXT - security: - - Authorization: [] - /whitelabel/domains/subuser: - get: - operationId: GET_whitelabel-domains-subuser - summary: List the domain whitelabel associated with the given user. - tags: - - Whitelabel - Domains - 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. | - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - delete: - operationId: DELETE_whitelabel-domains-subuser - summary: Disassociate a domain whitelabel from a given user. - tags: - - Whitelabel - Domains - 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. | - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: + 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 - security: - - Authorization: [] - '/whitelabel/domains/{domain_id}/subuser': - parameters: - - name: domain_id - in: path - required: true - type: string - post: - operationId: POST_whitelabel-domains-domain_id-subuser - summary: Associate a domain whitelabel with a given user. - tags: - - Whitelabel - Domains - 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. | - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: + 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 authenticated domain. + required: + - host + - type + - data + - valid properties: - username: + host: type: string - description: Username to associate with the domain whitelabel. - required: - - username - example: - username: jane@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - /whitelabel/ips: - get: - operationId: GET_whitelabel-ips - summary: Retrieve all IP whitelabels - tags: - - Whitelabel - IPs - 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). - 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. + 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 + - username + - user_id + - ips + - custom_spf + - default + - legacy + - automatic_security + - valid + - dns + 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 + example: + disabled: false + email: example@example.com + id: 1234 + username: example_subuser + mail_settings_address_whitelabel: + title: 'Mail Settings: Address Whitelabel' + type: object + properties: + enabled: + type: boolean + description: 'Indicates if you have an email address whitelist enabled. ' + list: + type: array + description: All email addresses that are currently on the whitelist. + items: type: string - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - post: - operationId: POST_whitelabel-ips - summary: Create an IP whitelabel - tags: - - Whitelabel - IPs - 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: + example: + enabled: true + list: + - email1@example.com + - example.com + link_branding_200_response: + title: Link Branding 200 Response + type: object + properties: + id: + type: integer + description: The ID of the branded link. + domain: + type: string + description: The root domain of the branded link. + subdomain: + type: string + description: The subdomain used to generate the DNS records for this link branding. This subdomain must be different from the subdomain used for your authenticated domain. + username: + type: string + description: The username of the account that this link branding is associated with. + user_id: + type: integer + description: The ID of the user that this link branding is associated with. + default: + type: boolean + description: Indicates if this is the default link branding. + enum: + - true + - false + valid: + type: boolean + description: Indicates if this link branding is valid. + enum: + - true + - false + legacy: + type: boolean + description: 'Indicates if this link branding was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you''ll need to create new link branding if you need to update it.' + enum: + - true + - false + dns: + type: object + description: The DNS records generated for this link branding. + required: + - domain_cname + properties: + domain_cname: type: object + description: The DNS record generated to point to your link branding subdomain. + required: + - valid + - type + - host + - data properties: - ip: + 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 generated. + enum: + - cname + - txt + - mx + host: + type: string + description: The domain that this link branding will use for the links in your email. + data: + type: string + description: The domain that the DNS record points to. + owner_cname: + type: object + description: The DNS record generated to verify who created the link branding. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + enum: + - true + - false + type: type: string - description: The IP address that you want to whitelabel. - subdomain: + description: The type of DNS record generated. + enum: + - cname + - txt + - mx + host: 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: + description: Used to verify the link branding. The subdomain of this domain is the ID of the user who created the link branding. + data: type: string - description: 'The root, or sending, domain that will be used to send message from the IP.' + description: The domain that the DNS record points to. required: - - ip - - subdomain - - domain - example: - ip: 192.168.1.1 - subdomain: email - domain: example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - 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 + - valid + - host + - data + required: + - id + - domain + - username + - user_id + - default + - valid + - legacy + - dns + from_email_object: + title: From Email Object + type: object + properties: + email: + type: string + format: email + description: The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account. + name: + type: string + description: A name or title associated with the sending email address. + required: + - email + example: + email: jane_doe@example.com + name: Jane Doe + api_key_name_id_scopes: + title: 'API Key Name, ID, and 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' + example: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: Mail Send + scopes: + - mail.send + - 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 + - sender_verification_eligible + - sender_verification_legacy + - 2fa_required + 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 + example: + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + - field: last_clicked + value: 01/02/2015 + operator: gt + and_or: and + - field: clicks.campaign_identifier + value: '513' + operator: eq + and_or: or + recipient_count: 1234 + api_key_name_id: + title: API Key Name and ID + type: object + properties: + api_key_id: + type: string + description: 'The ID of your API Key. ' + name: + type: string + description: The name of your API Key. + example: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: Mail Send + advanced_stats_opens: + title: 'Stats: Advanced Stats with Opens' + type: object + description: The individual events and their stats. + 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. + mail_settings_template: + title: '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. + example: + enabled: false + html_content: | +

<% body %>Example

+ ip_warmup_response: + title: 'IP Warmup: IP' + type: array + items: + type: object + properties: + ip: + type: string + description: The IP address. + start_date: + type: integer + description: A Unix timestamp indicating when the IP address entered warmup mode. + required: + - ip + - start_date + example: + - ip: 0.0.0.0 + start_date: 1409616000 + monitor: + title: Create monitor settings request + type: object + properties: + email: + type: string + description: The email address to which Sendgrid should send emails for monitoring. + format: email + frequency: + type: number + description: 'The frequency at which to forward monitoring emails. An email will be sent when your subuser sends this many (e.g., 1,000) emails.' + required: + - email + - frequency + example: + email: example@example.com + frequency: 50000 + global_error_response_schema: + title: Global Error Response Schema + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + description: the error message + field: + type: + - string + - 'null' + description: the field that generated the error + help: + type: object + description: helper text or docs for troubleshooting + required: + - message + id: + type: string + example: + errors: + - field: field_name + message: error message + advanced_stats_mailbox_provider: + title: 'Stats: Advanced Stats for Mailbox Provider' + description: The individual events and their stats. + allOf: + - $ref: '#/definitions/advanced_stats_clicks_opens' + - type: object + description: The individual events and their stats. + properties: + 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. + requests: + type: integer + description: The number of emails that were requested to be delivered. + processed: + type: integer + description: 'Requests from your website, application, or mail client via SMTP Relay or the Web API that SendGrid processed.' + spam_reports: + type: integer + description: The number of recipients who marked your email as spam. + contactdb_custom_field_with_id: + title: ContactDB Custom field schema with ID. + allOf: + - $ref: '#/definitions/contactdb_custom_field' + - type: object + properties: + id: + type: number + description: The ID of the custom field. + ip_pool: + title: 'IP Pools: Pool' + type: object + properties: + name: + type: string + description: The name of the IP pool. + maxLength: 64 + required: + - name + google_analytics_settings: + title: 'Settings: Google Analytics' + 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. + example: + enabled: true + utm_source: sendgrid.com + utm_medium: email + utm_term: '' + utm_content: '' + utm_campaign: website + event-webhook-response: + title: 'Webhooks: Event Webhook Response' + type: object + properties: + enabled: + type: boolean + description: Indicates if the event webhook is enabled. + url: + type: string + description: The URL that you want the event webhook to POST to. + group_resubscribe: + type: boolean + description: Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event. + delivered: + type: boolean + description: Message has been successfully delivered to the receiving server. + group_unsubscribe: + type: boolean + description: 'Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event.' + spam_report: + type: boolean + description: Recipient marked a message as spam. + bounce: + type: boolean + description: Receiving server could not or would not accept message. + deferred: + type: boolean + description: Recipient's email server temporarily rejected message. + unsubscribe: + type: boolean + description: Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event. + processed: + type: boolean + description: Message has been received and is ready to be delivered. + open: + type: boolean + description: Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event. + click: + type: boolean + description: Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event. + dropped: + type: boolean + description: 'You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota' + oauth_client_id: + type: string + description: The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. + oauth_token_url: + type: string + description: The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. + required: + - enabled + - url + - group_resubscribe + - delivered + - group_unsubscribe + - spam_report + - bounce + - deferred + - unsubscribe + - processed + - open + - click + - dropped + user_profile: + title: 'User: Profile' + type: object + properties: + address: + type: string + description: The street address for this user profile. + address2: + type: string + description: An optional second line for the street address of this user profile. + city: + type: string + description: The city for the user profile. + company: + type: string + description: That company that this user profile is associated with. + country: + type: string + description: Th country of this user profile. + first_name: + type: string + description: The first name of the user. + last_name: + type: string + description: The last name of the user. + phone: + type: string + description: The phone number for the user. + state: + type: string + description: The state for this user. + website: + type: string + description: The website associated with this user. + zip: + type: string + description: The zip code for this user. + example: + address: '1451 Larimer Street, 3rd floor' + address2: '' + city: 'Denver, CO' + company: SendGrid + country: US + first_name: Matthew + last_name: Bernier + phone: '7208788003' + state: CO + website: 'http://sendgrid.com' + zip: '80202' + mail_settings_footer: + title: '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. + example: + enabled: true + html_content: Example HTML content + plain_content: Example plain content + category_stats: + title: 'Stats: 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 + example: + date: '2015-01-01' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: cat1 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: cat2 + type: category + parse-setting: + title: Parse Setting + type: object + properties: + url: type: string - get: - operationId: GET_whitelabel-ips-id - summary: Retrieve an IP whitelabel - tags: - - Whitelabel - IPs - 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). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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. - security: - - Authorization: [] - delete: - operationId: DELETE_whitelabel-ips-id - summary: Delete an IP whitelabel - tags: - - Whitelabel - IPs - 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). - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The errors preventing the IP whitelabel from being deleted. - items: - type: object - properties: - message: - type: string - description: A message explaining why the IP whitelabel could not be deleted. - examples: - application/json: - errors: - - message: Whitelabel ip not found. - security: - - Authorization: [] - '/whitelabel/ips/{id}/validate': - parameters: - - name: id - in: path - required: true + description: The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL. + hostname: + type: string + description: 'A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, `parse.yourdomain.com`.' + spam_check: + type: boolean + description: Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain. + send_raw: + type: boolean + description: 'Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to `true`, SendGrid will send a JSON payload of the content of your email.' + example: + url: 'http://email.myhostname.com' + hostname: myhostname.com + spam_check: false + send_raw: true + transactional_template: + title: 'Transactional Templates: Template' + allOf: + - $ref: '#/definitions/transactional-templates-template-lean' + - type: object + properties: + warning: + $ref: '#/definitions/transactional-template-warning' + example: + id: 33feeff2-5069-43fe-8853-428651e5be79 + name: example_name + 'updated_at ': '2021-04-28 13:12:46' + warning: + message: Sample warning message + generation: legacy + contactdb_list: + title: ContactDB lists + type: object + properties: + id: type: integer - post: - operationId: POST_whitelabel-ips-id-validate - summary: Validate an IP whitelabel - tags: - - Whitelabel - IPs - description: |- - **This endpoint allows you to validate an IP whitelabel.** - - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: - type: object - properties: - id: - type: integer - description: The id of the IP whitelabel. - valid: - type: boolean - description: Indicates if the IP whitelabel is valid. - enum: - - true - - false - validation_results: - type: object - description: The specific results of the validation. - properties: - a_record: - type: object - properties: - valid: - type: boolean - description: Indicates if the IP whitelabel could be validated. - enum: - - true - - false - reason: - type: - - 'null' - - string - description: The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated. - required: - - valid - - reason - required: - - id - - valid - - validation_results - examples: - application/json: - id: 1 - valid: true - validation_results: - a_record: - valid: true - reason: null - '404': - description: Unexpected error in API call. See HTTP response body for details. - schema: - type: object - properties: - errors: - type: array - description: The error messages for the failed validation. - items: - type: object - properties: - message: - type: string - description: A message describing why the IP could not be validated. - required: - - message - required: - - errors - examples: - application/json: - errors: - - message: Whitelabel ip not found. - '500': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The error messages for the failed validation. - items: - type: object - properties: - message: - type: string - description: A message describing why the IP whitelabel could not be validated. - required: - - message - required: - - errors - examples: - application/json: - errors: - - message: internal error getting rDNS - security: - - Authorization: [] - /whitelabel/links: - get: - operationId: GET_whitelabel-links - summary: Retrieve all link whitelabels - tags: - - Whitelabel - Links - 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). - produces: - - application/json - parameters: - - name: limit - in: query - description: Limits the number of results returned per page. - type: integer - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: + description: The reference ID of your list. + name: + type: string + description: The name of your list. Must be unique against all other list and segment names. + recipient_count: + type: integer + description: The count of recipients currently in the list. + required: + - id + - name + - recipient_count + example: + id: 1 + name: listname + recipient_count: 0 + suppression_group: + title: 'Suppressions: 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. + unsubscribes: + type: integer + description: The unsubscribes associated with this group. + required: + - id + - name + - description + mail_settings_bounce_purge: + title: '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. + example: + enabled: false + soft_bounces: 1234 + hard_bounces: null + transactional_template_version_output: + title: 'Transactional Templates: Version Output' + allOf: + - type: object + properties: + warnings: type: array items: - $ref: '#/definitions/link_whitelabel' - examples: - application/json: - - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: true - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - - id: 2 - domain: example2.com - subdomain: news - username: john@example.com - user_id: 8 - default: false - valid: false - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: news.example2.com - data: sendgrid.net - owner_cname: - valid: false - type: cname - host: 8.example2.com - data: sendgrid.net - security: - - Authorization: [] - post: - operationId: POST_whitelabel-links - summary: Create a Link Whitelabel - tags: - - Whitelabel - Links - 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: Number of domains to return. + $ref: '#/definitions/transactional-template-warning' + - $ref: '#/definitions/transactional_template_version_create' + - $ref: '#/definitions/transactional-templates-version-output-lean' + credentials: + title: Credentials + type: object + properties: + permissions: + type: object + properties: + api: + type: string + mail: + type: string + web: + type: string + username: + type: string + example: + address: 1234 example street + address2: null + city: Denver + company: Company name + country: US + email: example@example.com + first_name: Example + last_name: User + phone: (555) 555-5555 + state: CO + zip: '55555' + 'global:id': + title: 'Global: ID' + type: integer + mail_settings_forward_spam: + title: 'Mail Settings: Forward Spam' + type: object + properties: + email: + type: string + description: The email address where you would like the spam reports to be forwarded. + enabled: + type: boolean + description: Indicates if the Forward Spam setting is enabled. + example: + email: '' + enabled: true + campaign_request: + title: Campaigns 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 - default: 50 - - name: offset - in: query - description: Paging offset. + 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. Segments are limited to 10 segment IDs. + items: type: integer - default: 0 - - name: body - in: body - schema: + 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. + editor: + type: string + enum: + - code + - design + description: The editor used in the UI. + required: + - title + 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 + subuser_stats: + title: subuser_stats + type: object + properties: + date: + type: string + description: The date the statistics were gathered. + stats: + type: array + description: The list of statistics. + items: + type: object + properties: + first_name: + type: string + description: The first name of the subuser. + last_name: + type: string + description: The last name of the subuser. + 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. + name: + type: string + description: The username of the subuser. + type: + type: string + description: The type of account. + example: + date: '2016-02-01' + stats: + - first_name: John + last_name: Doe + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 5 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 10 + processed: 10 + requests: 10 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: user1 + type: subuser + user_scheduled_send_status: + title: 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 + example: + batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + status: pause + advanced_stats_clicks_opens: + title: 'Stats: Advanced Stats with Clicks and Opens' + description: The individual events and their stats. + allOf: + - $ref: '#/definitions/advanced_stats_clicks' + - $ref: '#/definitions/advanced_stats_opens' + contactdb_segments_with_id: + title: 'ContactDB:: Segments with ID' + allOf: + - type: object + properties: + id: + type: number + description: The ID of the segment. + required: + - id + - $ref: '#/definitions/contactdb_segments' + advanced_stats_clicks: + title: 'Stats: Advanced Stats with Clicks' + type: object + description: The individual events and their stats. + 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. + contactdb_recipient: + title: '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 + mail_settings_patch: + title: 'Mail Settings: Patch' + type: object + properties: + enabled: + type: boolean + description: Indicates if the mail setting is enabled. + email: + type: string + description: The email address of the recipient. + example: + enabled: true + email: email@example.com + mail_settings_forward_bounce: + title: 'Mail Settings: Forward Bounce' + type: object + properties: + email: + type: + - string + - 'null' + description: The email address that you would like your bounce reports forwarded to. + enabled: + type: boolean + description: Indicates if the bounce forwarding mail setting is enabled. + example: + enabled: false + email: null + mail_batch_id: + title: Mail Batch ID + type: object + properties: + batch_id: + type: string + pattern: '^[a-zA-Z0-9\-\_]' + required: + - batch_id + example: + batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + subuser_post: + title: '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 + example: + username: example_subuser + user_id: 1234 + email: example@example.com + signup_session_token: '' + authorization_token: '' + credit_allocation: + type: unlimited + contactdb_recipient_count: + title: 'ContactDB: Recipient Count' + type: object + properties: + recipient_count: + type: number + description: The count of recipients. + required: + - recipient_count + example: + recipient_count: 1234 + 'authentication::domain': + title: Domain Authentication - Mandatory Subdomain + type: object + properties: + id: + type: number + description: The ID of the authenticated domain. + user_id: + type: number + description: The ID of the user that this domain is associated with. + subdomain: + type: string + description: The subdomain to use for this authenticated domain. + domain: + type: string + description: The domain to be authenticated. + username: + type: string + description: The username that this domain will be associated with. + ips: + type: array + description: The IPs to be included in the custom SPF record for this authenticated domain. + items: + type: string + custom_spf: + type: boolean + description: Indicates whether this authenticated domain uses custom SPF. + default: + type: boolean + description: Indicates if this is the default authenticated domain. + legacy: + type: boolean + description: 'Indicates if this authenticated domain was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you''ll need to create a new authenticated domain if you need to update it.' + automatic_security: + type: boolean + description: Indicates if this authenticated domain uses automated security. + valid: + type: boolean + description: Indicates if this is a valid authenticated domain. + dns: + type: object + description: The DNS records used to authenticate the sending domain. + required: + - mail_cname + - dkim1 + - dkim2 + properties: + mail_cname: 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 + description: The CNAME for your sending domain that points to sendgrid.net. required: - - domain - - subdomain - example: - domain: example.com - subdomain: mail - default: true - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '201': - description: '' - schema: - $ref: '#/definitions/link_whitelabel' - examples: - application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - security: - - Authorization: [] - '/whitelabel/links/{id}': - parameters: - - name: id - in: path - description: The id of the link whitelabel you want to retrieve. - required: true - type: integer - get: - operationId: GET_whitelabel-links-id - summary: Retrieve a Link Whitelabel - tags: - - Whitelabel - Links - 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). - produces: - - application/json - parameters: - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - patch: - operationId: PATCH_whitelabel-links-id - summary: Update a Link Whitelabel - tags: - - Whitelabel - Links - 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object + - valid + - type + - host + - data properties: - default: + valid: type: boolean - description: 'Indicates if the link whitelabel is set as the default, or fallback, whitelabel.' - enum: - - true - - false - example: - default: true - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - delete: - operationId: DELETE_whitelabel-links-id - summary: Delete a Link Whitelabel - tags: - - Whitelabel - Links - 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). - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - security: - - Authorization: [] - /whitelabel/links/default: - get: - operationId: GET_whitelabel-links-default - summary: Retrieve a Default Link Whitelabel - tags: - - Whitelabel - Links - 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). - produces: - - application/json - parameters: - - name: domain - in: query - description: The domain to match against when finding a corresponding link whitelabel. - type: string - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - 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: - operationId: POST_whitelabel-links-id-validate - summary: Validate a Link Whitelabel - tags: - - Whitelabel - Links - 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). - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '200': - description: '' - schema: + 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: - id: - type: integer - description: The id of the link whitelabel. valid: type: boolean - description: Indicates if the link whitelabel is valid. - enum: - - true - - false - validation_results: - type: object - description: The individual validations results for each of the DNS records associated with this link whitelabel. - required: - - domain_cname - properties: - domain_cname: - type: object - description: The DNS record generated for the sending domain used for this link whitelabel. - required: - - valid - - reason - properties: - valid: - type: boolean - description: Indicates if this DNS record is valid. - enum: - - true - - false - reason: - type: - - string - - 'null' - description: 'Null if the DNS record is valid. If the DNS record is invalid, this will explain why.' - owner_cname: - type: object - description: The DNS record created to verify the link whitelabel. - properties: - valid: - type: boolean - description: Indicates if the DNS record is valid. - enum: - - true - - false - reason: - type: - - 'null' - - string - description: 'Null if valid. If the DNS record is invalid, this will explain why.' - required: - - valid - - reason - required: - - id - - valid - - validation_results - examples: - application/json: - id: 1 - valid: true - validation_results: - domain_cname: - valid: false - reason: Expected CNAME to match "sendgrid.net." but found "example.com.". - owner_cname: - valid: true - reason: null - '500': - description: '' - schema: + 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 - 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 + description: A DNS record. required: - - errors - examples: - application/json: - errors: - - message: internal error getting CNAME - security: - - Authorization: [] - /whitelabel/links/subuser: - get: - operationId: GET_whitelabel-links-subuser - summary: Retrieve Associated Link Whitelabel - tags: - - Whitelabel - Links - 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). - produces: - - application/json - parameters: - - name: username - in: query - description: The username of the subuser to retrieve associated link whitelabels for. - required: true - type: string - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] - delete: - operationId: DELETE_whitelabel-links-subuser - summary: Disassociate a Link Whitelabel - tags: - - Whitelabel - Links - 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). - parameters: - - name: username - in: query - description: The username of the subuser account that you want to disassociate a link whitelabel from. - required: true - type: string - - name: body - in: body - schema: - type: 'null' - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - responses: - '204': - description: '' - schema: - type: object - 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: - operationId: POST_whitelabel-links-link_id-subuser - summary: Associate a Link Whitelabel - tags: - - Whitelabel - Links - 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). - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object + - valid + - type + - host + - data properties: - username: + valid: + type: boolean + description: Indicates if this is a valid DNS record. + type: type: string - description: The username of the subuser account that you want to associate the link whitelabel with. - example: - username: jane@example.com - - $ref: '#/parameters/trait:onBehalfOfSubuser:on-behalf-of' - 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 - security: - - Authorization: [] -parameters: - 'trait:authorizationHeader:Authorization': - name: Authorization - in: header - required: true - type: string - default: Bearer <> - 'trait:onBehalfOfSubuser:on-behalf-of': - name: on-behalf-of - in: header - type: string - default: subuser_ -definitions: - mail_settings_spam_check: - title: '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. + 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: - - enabled - example: - enabled: false - max_score: 6 - url: 'http://example.com' - suppression_group_unsubscribes: - title: 'Suppressions: Suppression Group with Unsubscribes' + - id + - user_id + - subdomain + - domain + - username + - ips + - custom_spf + - default + - legacy + - automatic_security + - valid + - dns + contactdb_custom_field_with_id_value: + title: ContactDB Custom field schema. allOf: - - $ref: '#/definitions/suppression_group' - - properties: - unsubscribes: - type: integer - description: The unsubscribes associated with this group. - required: - - unsubscribes - type: object - partner_settings_new_relic: - title: 'Partner Settings: New Relic' + - $ref: '#/definitions/contactdb_custom_field_with_id' + - type: object + properties: + value: + type: + - string + - 'null' + description: The value of this recipient's custom field + transactional_template_version_create: + title: 'Transactional Templates: Version Create' type: object properties: - enable_subuser_statistics: - type: boolean - description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. - enabled: + active: + type: integer + description: 'Set the version as the active version associated with the template (0 is inactive, 1 is active). 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 transactional template version. + maxLength: 100 + html_content: + type: string + description: The HTML content of the version. Maximum of 1048576 bytes allowed. + maxLength: 1048576 + plain_content: + type: string + description: Text/plain content of the transactional template version. Maximum of 1048576 bytes allowed. + maxLength: 1048576 + default: + generate_plain_content: type: boolean - description: 'Indicates if this setting is enabled. ' - license_key: + description: 'If true, plain_content is always generated from html_content. If false, plain_content is not altered.' + default: true + subject: type: string - description: The license key provided with your New Relic account. + description: Subject of the new transactional template version. + maxLength: 255 + editor: + type: string + enum: + - code + - design + description: The editor used in the UI. + test_data: + type: string + description: 'For dynamic templates only, the mock json data that will be used for template preview and test sends.' required: - - enabled - - license_key - subscription_tracking_settings: - title: 'Settings: Subscription Tracking' + - name + - subject + example: + template_id: Excepteur Ut qui + active: 1 + name: pariatur non incididunt commodo + html_content: dolor + generate_plain_content: false + subject: aliquip nulla Ut + editor: design + plain_content: labore dolore + transactional-templates-version-output-lean: + title: 'Transactional Templates: Version Output Lean' type: object properties: - enabled: - type: boolean - description: Indicates if subscription tracking is enabled. - html_content: + id: type: string - description: 'The information and HTML for your unsubscribe link. ' - landing: + description: ID of the transactional template version. + format: uuid + template_id: 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: + description: ID of the transactional template. + active: + type: integer + description: Set the 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: '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: + description: Name of the transactional template version. + maxLength: 100 + subject: type: string - description: Your custom defined replacement tag for your templates. Use this tag to place your unsubscribe content anywhere in your emailtemplate. - url: + description: Subject of the new transactional template version. + maxLength: 255 + updated_at: type: string - description: The URL where you would like your users sent to unsubscribe. - campaign_response: - title: Campaigns Response - allOf: - - $ref: '#/definitions/campaign_request' - - type: object - properties: - status: - type: string - description: The status of your campaign. - id: - type: integer - required: - - status - contactdb_recipient_response: - title: 'ContactDB: Recipient response' + description: The date and time that this transactional template version was updated. + generate_plain_content: + type: boolean + description: 'If true, plain_content is always generated from html_content. If false, plain_content is not altered.' + default: true + editor: + type: string + enum: + - code + - design + description: The editor used in the UI. + thumbnail_url: + type: string + description: A Thumbnail preview of the template's html content. + transactional-templates-template-lean: + title: 'Transactional Templates: Template Lean' type: object properties: - error_count: - type: number - default: 0 - description: The number of errors found while adding recipients. - error_indices: + id: + type: string + description: The ID of the transactional template. + minLength: 36 + maxLength: 36 + format: uuid + name: + type: string + description: The name for the transactional template. + maxLength: 100 + generation: + type: string + description: Defines the generation of the template. + enum: + - legacy + - dynamic + 'updated_at ': + type: string + description: The date and time that this transactional template version was updated. + pattern: '^(\d{4}-\d{2}-\d{2}) ((\d{2}):(\d{2}):(\d{2}))$' + versions: type: array - default: [] - description: 'The indices of the recipient(s) sent that caused the error. ' + description: The different versions of this transactional template. items: - type: number - new_count: - type: number - default: 0 - description: The count of new recipients added to the contactdb. - persisted_recipients: + $ref: '#/definitions/transactional-templates-version-output-lean' + required: + - id + - name + - generation + - 'updated_at ' + example: + id: 0c314114-a2b7-4523-8cbc-a293d7d19007 + name: example_name + generation: legacy + 'updated_at ': '2021-04-28 13:12:46' + versions: [] + custom-fields-by-id: + title: custom-fields-by-id + type: object + example: + w1: '2002-10-02T15:00:00Z' + w33: 9.5 + e2: Coffee is a beverage that puts one to sleep when not drank. + custom-fields-by-name: + title: custom-fields-by-name + type: object + example: + birthday: '2002-10-02T15:00:00Z' + shoe_size: 9.5 + favoriteQuote: Coffee is a beverage that puts one to sleep when not drank. + contact-details: + title: contact-details + type: object + properties: + address_line_1: + type: string + address_line_2: + type: string + alternate_emails: 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: + city: + type: string + country: + type: string + email: + type: string + first_name: + type: string + id: + type: string + last_name: + type: string + postal_code: + type: string + state_province_region: + type: string + list_ids: 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 - example: - error_count: 1 - error_indices: - - 2 - new_count: 2 - persisted_recipients: - - YUBh - - bWlsbGVyQG1pbGxlci50ZXN0 - updated_count: 0 - errors: - - message: Invalid email. - error_indices: - - 2 - stats: - title: 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. - contactdb_segments_conditions: - title: 'ContactDB: Segments: Conditions' + created_at: + type: string + description: The ISO8601 timestamp when the contact was created. + updated_at: + type: string + description: The ISO8601 timestamp when the contact was updated. + _metadata: + $ref: '#/definitions/selfmetadata' + custom_fields: + $ref: '#/definitions/custom-fields-by-name' + required: + - id + - list_ids + - created_at + - updated_at + contact-import: + title: contact-import + type: object + properties: + id: + type: string + description: The job ID. + status: + type: string + description: 'The job state. Allowed values: `pending`, `completed`, `errored`, or `failed`.' + job_type: + type: string + description: 'The job type. Allowed values: `upsert`, or `delete`.' + results: + type: object + description: Result map of the import job. + properties: + requested_count: + description: Requested contact count from the import. + type: number + created_count: + description: Created contact count from the import. + type: number + updated_count: + description: Updated contact count from the import. + type: number + deleted_count: + description: Count of deleted contacts that resulted in error. + type: number + errored_count: + description: Count of imported contacts that resulted in error. + type: number + errors_url: + type: string + description: The download URL of the file which provides information about any errors. + started_at: + description: The ISO8601 timestamp when the job was created. + type: string + finished_at: + description: The ISO8601 timestamp when the job was finished. + type: string + single-contact-request: + title: single contact request + type: object + properties: + list_ids: + type: array + minItems: 0 + maxItems: 100 + description: The contact's list IDs. + items: + type: string + format: uuid + contact: + type: object + properties: + primary_email: + type: string + alternate_emails: + type: string + first_name: + type: string + last_name: + type: string + address_line_1: + type: string + address_line_2: + type: string + city: + type: string + state_province_region: + type: string + postal_code: + type: string + country: + type: string + custom_fields: + type: object + properties: + custom_field_name1: + type: string + custom_field_name2: + type: string + contact-export: + title: contact-export type: object properties: - field: - type: string - value: + id: type: string - operator: + status: type: string enum: - - eq - - ne - - lt - - gt - - contains - and_or: + - pending + - ready + - failure + description: 'The export job''s status. Allowed values: `pending`, `ready`, or `failure`.' + created_at: type: string - enum: - - and - - or - - '' + description: The ISO8601 timestamp when the export was begun. + updated_at: + type: string + description: The ISO8601 timestamp when the export was updated. + completed_at: + type: string + description: The ISO8601 timestamp when the export was completed. + expires_at: + type: string + description: The ISO8601 timestamp when the exported file on S3 will expire. + urls: + type: array + description: One or more download URLs for the contact file if the status is `ready`. + items: + type: string + message: + type: string + description: A human readable message if the status is `failure`. + _metadata: + $ref: '#/definitions/metadata' + contact_count: + type: integer + description: The total number of exported contacts. required: - - field - - value - - operator - suppression_bounce: - title: 'Suppression: Bounce' + - id + - status + - created_at + - updated_at + - expires_at + contact-summary: + title: contact-summary 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: + description: Primary email address. + first_name: type: string - description: Enhanced SMTP bounce response - 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 - ip_whitelabel: - title: Whitelabel - IPs - 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: + description: Contact UUID. + last_name: type: string - description: The reverse DNS record for the IP address. This points to the IP whitelabel subdomain. - users: + list_ids: type: array - description: The users who are able to send mail from the IP. + description: List UUID linked with this contact. 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. + type: string + created_at: + type: number + description: Unix Epoch Timestamp. + updated_at: + type: number + description: Unix Epoch Timestamp. + _metadata: + $ref: '#/definitions/selfmetadata' required: - id - - ip - - rdns - - users - - subdomain - - domain - - valid - - legacy - - a_record - 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 - contacts: - title: Contacts + - list_ids + - created_at + - updated_at + contact-request: + title: contact-request type: object properties: - address: + address_line_1: type: string - address2: - type: object - city: + description: The first line of the address. + maxLength: 100 + address_line_2: type: string - company: + description: An optional second line for the address. + maxLength: 100 + alternate_emails: + type: array + description: Additional emails associated with the contact. + minItems: 0 + maxItems: 5 + items: + type: string + maxLength: 254 + city: type: string + description: The contact's city. + maxLength: 60 country: type: string + description: The contact's country. Can be a full name or an abbreviation. + maxLength: 50 email: type: string + description: The contact's primary email. This is required to be a valid email. + maxLength: 254 first_name: type: string + description: The contact's personal name. + maxLength: 50 last_name: type: string - phone: - type: string - state: + description: The contact's family name. + maxLength: 50 + postal_code: type: string - zip: + description: The contact's ZIP code or other postal code. + state_province_region: type: string - senderID: - title: Sender ID + description: 'The contact''s state, province, or region.' + maxLength: 50 + custom_fields: + $ref: '#/definitions/custom-fields-by-id' + required: + - email + contact-details2: + title: contact-details2 type: object properties: id: - type: integer - description: The unique identifier of the sender identity. - nickname: type: string - description: A nickname for the sender identity. Not used for sending. - from: - type: object - properties: - email: - type: string - description: This is where the email will appear to originate from for your recipient - name: - type: string - description: This is the name appended to the from email field. IE - Your name or company name. - required: - - email - reply_to: - type: object - properties: - email: - type: string - description: This is the email that your recipient will reply to. - name: - type: string - description: This is the name appended to the reply to email field. IE - Your name or company name. - address: + minLength: 36 + maxLength: 36 + format: uuid + first_name: type: string - description: The physical address of the sender identity. - address_2: + last_name: + type: string + unique_name: + type: string + email: + type: string + format: email + alternate_emails: + type: + - array + - 'null' + items: + type: string + format: email + address_line_1: + type: string + address_line_2: type: string - description: Additional sender identity address information. city: type: string - description: The city of the sender identity. - state: + state_province_region: type: string - description: The state of the sender identity. - zip: + country: + type: string + postal_code: + type: string + phone_number: + type: string + whatsapp: + type: string + line: + type: string + facebook: + type: string + list_ids: + type: array + items: + type: string + format: uuid + segment_ids: + type: array + items: + type: string + format: uuid + custom_fields: + type: object + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + _metadata: + $ref: '#/definitions/selfmetadata' + required: + - id + - list_ids + - created_at + - updated_at + selfmetadata: + title: selfMetadata + type: object + properties: + self: + type: string + description: A link to this object. + error: + title: error + type: object + properties: + message: + type: string + field: + type: string + error_id: + type: string + parameter: + type: string + required: + - message + link: + title: Link + type: object + properties: + rel: + type: string + href: + type: string + metadata: + title: metadata + type: object + properties: + prev: + type: string + format: uri + description: 'The URL of the previous page of results. If this field isn''t present, you''re at the start of the list.' + self: + type: string + format: uri + description: The URL of the current page of results. + next: + type: string + format: uri + description: 'The URL of the next page of results. If this field isn''t present, you''re at the end of the list.' + count: + type: number + description: 'The number of items in the entire list, i.e., across all pages.' + webhook: + title: webhook + type: object + properties: + url: + type: string + description: The URL to invoke in the webhook + nonce: + type: string + description: The one time nonce to use when "signature" is "hmac-sha1" + minLength: 8 + maxLength: 32 + required: + - url + - nonce + list: + title: list + type: object + properties: + id: type: string - description: The zipcode of the sender identity. - country: + description: The generated ID for your list. + minLength: 36 + maxLength: 36 + format: uuid + name: type: string - description: The country of the sender identity. - verified: - type: boolean - description: If the sender identity is verified or not. Only verified sender identities can be used to send email. - updated_at: - type: integer - description: The time the sender identity was last updated. - created_at: + description: The name you gave your list. + contact_count: type: integer - description: The time the sender identity was created. - locked: + description: The number of contacts currently stored on the list. + _metadata: + $ref: '#/definitions/selfmetadata' + reserved_field_definitions_response: + title: reserved_field_definitions_response + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + field_type: + type: string + enum: + - Text + - Number + - Date + read_only: type: boolean - description: 'A sender identity is locked when it is associated to a campaign in the Draft, Scheduled, or In Progress status. You cannot update or delete a locked sender identity.' + default: false + description: When `true` this means API consumers are unable to set the value of this field on contacts. required: - - nickname - - address - - city - - country + - name + - field_type example: - id: 1 - nickname: My Sender ID - from: - email: from@example.com - name: Example INC - reply_to: - email: replyto@example.com - name: Example INC - address: 123 Elm St. - address_2: Apt. 456 - city: Denver - state: Colorado - zip: '80202' - country: United States - verified: true - updated_at: 1449872165 - created_at: 1449872165 - locked: false - 'global:empty_request': - title: 'Global: Request Empty Body' - type: 'null' - contactdb_custom_field: - title: ContactDB Custom field schema. + id: _rf20_T + name: automation_id + field_type: Text + read_only: true + custom_field_definitions_response: + title: custom_field_definitions_response type: object properties: + id: + type: string name: type: string - description: The name of the field - type: + minLength: 1 + maxLength: 100 + field_type: type: string - description: The type of the field. enum: - - date - - text - - number + - Text + - Number + - Date + required: + - id + - name + - field_type example: - name: first_name - type: text - 'whitelabel:domain_spf': - title: Whitelabel - Domain + id: a1_D + name: custom_field_name + field_type: Date + segment_write: + title: segment_write + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + query_dsl: + type: string + description: Use this field for adding your query string. + required: + - name + - query_dsl + segment_summary: + title: segment_summary type: object properties: id: + type: string + minLength: 36 + maxLength: 36 + format: uuid + contacts_count: type: integer - description: The ID of the domain whitelabel. - domain: + created_at: type: string - description: The domain that this whitelabel was created for. - subdomain: + description: | + ISO8601 of created timestamp + format: date-time + name: type: string - description: The subdomain that was used to create this whitelabel. - username: + minLength: 1 + maxLength: 100 + parent_list_id: 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: + minLength: 36 + maxLength: 36 + format: uuid + description: 'The id of the list if this segment is a child of a list. This implies the query `AND CONTAINS(list_ids, ${parent_list_id})`' + sample_updated_at: + type: string + description: ISO8601 timestamp the sample was last updated + format: date-time + updated_at: + type: string + description: ISO8601 timestamp the object was last updated + format: date-time + next_sample_update: + type: string + description: ISO8601 string that is equal to `sample_updated_at` plus an internally calculated offset that depends on how often contacts enter or exit segments as the scheduled pipeline updates the samples. + required: + - id + - contacts_count + - created_at + - sample_updated_at + - updated_at + segment_query_json: + title: segment_query_json + type: object + properties: + contacts: 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: + op: + type: string + l: type: object - description: The SPF record for the root domain. - required: - - host - - type - - data - - valid properties: - host: + op: 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: + l: + type: object + properties: + op: + type: string + l: + type: object + properties: + v: + type: string + t: + type: string + r: + type: object + properties: + v: + type: string + t: + type: string + r: + type: object + properties: + op: + type: string + l: + type: object + properties: + v: + type: string + t: + type: string + args: + type: array + items: + type: object + properties: + v: + type: string + t: + type: string + r: + type: object + properties: + v: + type: string + t: + type: string + r: 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: + op: 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 - 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 - example: - disabled: false - email: example@example.com - id: 1234 - username: example_subuser - mail_settings_address_whitelabel: - title: 'Mail Settings: Address Whitelabel' + l: + type: object + properties: + v: + type: string + t: + type: string + r: + type: object + properties: + v: + type: array + items: + type: string + t: + type: string + contact_response: + title: contact_response type: object properties: - enabled: - type: boolean - description: 'Indicates if you have an email address whitelist enabled. ' - list: + contact_id: + type: string + maxLength: 36 + pattern: '[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}' + format: uuid + primary_email: + type: string + minLength: 3 + maxLength: 254 + format: email + alternate_emails: type: array - description: All email address that are currently on the whitelist. + uniqueItems: true + minItems: 0 items: type: string - example: - enabled: true - list: - - email1@example.com - - example.com - link_whitelabel: - title: Whitelabel - Links - type: object - properties: - id: - type: integer - description: The id of the link whitelabel. - domain: + minLength: 3 + maxLength: 254 + format: email + first_name: type: string - description: The root domain for this link whitelabel. - subdomain: + minLength: 1 + last_name: 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: + minLength: 1 + address_line_1: type: string - description: The username of the account that this link whitelabel is associated with. - user_id: + minLength: 0 + address_line_2: + type: string + minLength: 0 + city: + type: string + minLength: 0 + pattern: '^[a-zA-Z\u0080-\u024F\s\/\-\)\(\`\.\"\'']+$' + state_province_region: + type: string + minLength: 0 + postal_code: 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: + country: + type: string + minLength: 0 + list_ids: + type: array + uniqueItems: true + description: IDs of all lists the contact is part of. + items: + type: string + format: uuid + custom_fields: type: object - description: The DNS records generated for this link whitelabel. - required: - - domain_cname + minProperties: 0 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. - data: - type: string - description: The domain that the DNS record points to. - owner_cname: + custom_field_name1: + type: string + minLength: 0 + custom_field_name2: + type: string + minLength: 0 + required: + - contact_id + - primary_email + - alternate_emails + - first_name + - last_name + - address_line_1 + - address_line_2 + - city + - state_province_region + - postal_code + - country + - custom_fields + TNE-senderID: + title: Sender ID Response Body + allOf: + - type: object + properties: + id: + type: integer + description: The unique identifier of the sender. + - $ref: '#/definitions/senders-id-request-body' + - type: object + properties: + verified: type: object - description: The DNS record generated to verify who created the link whitelabel. + description: Only verified sender identities can be used to send email. properties: - valid: + status: 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. - data: - type: string - description: The domain that the DNS record points to. - required: - - valid - - host - - data - required: - - id - - domain - - subdomain - - username - - user_id - - default - - valid - - legacy - - dns - email_object: - title: Email Object + description: Whether the sender identity has been verified. Only verified sender identities can be used to send email. + reason: + type: + - string + - 'null' + description: 'The reason for a verification failure, or null if verification succeeeded or has yet to take place.' + updated_at: + type: integer + description: The time the sender identity was last updated. + created_at: + type: integer + description: The time the sender identity was created. + locked: + type: boolean + description: 'A sender identity is locked when it is associated with a campaign in the Draft, Scheduled, or In Progress state. You can''t update or delete a locked sender identity.' + api-error: + title: error type: object properties: - email: + message: type: string - format: email - name: + field: + type: string + error_id: type: string - description: The name of the person to whom you are sending an email. required: - - email - api_key_name_id_scopes: - title: 'API Key Name, ID, and Scopes' + - message + - field + - error_id + api-errors: + title: errors + type: object + properties: + errors: + type: array + items: + $ref: '#/definitions/api-error' + _metadata: + title: _metadata + type: object + properties: + prev: + type: string + format: uri + self: + type: string + format: uri + next: + type: string + format: uri + count: + type: integer + minimum: 0 + design-input: + title: Design Input allOf: + - $ref: '#/definitions/design-duplicate-input' + - $ref: '#/definitions/design-common-fields' - type: object properties: - scopes: - type: array - description: The permissions this API Key has access to. - items: - type: string - - $ref: '#/definitions/api_key_name_id' + html_content: + type: string + description: The HTML content of the Design. + maxLength: 1048576 + plain_content: + type: string + description: Plain text content of the Design. + maxLength: 1048576 + default: + required: + - html_content example: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - scopes: - - user.profile.read - - user.profile.update - contactdb_segments: - title: Create a Segment request + name: 'Ahoy, World!' + editor: design + subject: Getting Started + html_content: |- + + + + + + + + + + + + + + +
+
+ + + + +
+ + + + +
+ + + + +
+ + + + + +
+ + + + + + + + + +
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

+ +
+
+
+
+
+ + + plain_content: |- + Ahoy, World! + + {{Sender_Name}} + + {{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}} + + Unsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} ) + design-output: + title: Design Output + allOf: + - $ref: '#/definitions/design-output-summary' + - $ref: '#/definitions/design-input' + design-output-summary: + title: Design Output - Summary + allOf: + - type: object + properties: + id: + type: string + description: ID of the Design. + format: uuid + updated_at: + type: string + description: Datetime that Design was last updated. + format: ISO 8601 date-time + created_at: + type: string + description: Datetime that Design was created. + format: ISO 8601 date-time + thumbnail_url: + type: string + description: A Thumbnail preview of the template's html content. + - $ref: '#/definitions/design-duplicate-input' + - $ref: '#/definitions/design-common-fields' + example: + result: + - id: 3247eaea-c912-42a3-b0bc-60bdaf210396 + name: Welcome Email + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/llny8o5b3m636z92p7hbjnmq1jvpka39p370jwtin2s1wxv7x1sgm0y5fk518d0s.png + subject: Welcom to the Cake or Pie Cafe + created_at: '2021-04-09T17:29:46Z' + updated_at: '2021-04-09T17:29:55Z' + editor: code + categories: + - welcome + - new customer + - id: 02dfd792-f31f-439a-a79e-5c47fbcfdbac + name: Monthly Promo + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/hfyxahd7ues2ajuoeoqq2xe6ibdasl1q89ox0y9ncya2ftpoicssmtf9ddus4c39.png + subject: Free Dozen Cupcakes + created_at: '2021-04-09T17:29:21Z' + updated_at: '2021-04-09T17:29:42Z' + editor: design + categories: + - promo + - coupon + - id: e54be823-19ef-4c6f-8b60-efd7514f492d + name: 'Duplicate: Ingrid & Anders' + generate_plain_content: true + thumbnail_url: //us-east-2-production-thumbnail-bucket.s3.amazonaws.com/12kni9gjpyb9uxmwr9vk7unycjr70u95zoyhe9sg2zounul2zg7dih1s20k13q2z.png + subject: Welcome to Ingrid & Anders! + created_at: '2020-10-09T17:33:46Z' + updated_at: '2021-04-07T19:57:52Z' + editor: design + categories: [] + _metadata: + self: 'https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I' + count: 3 + design-duplicate-input: + title: Design Duplicate Design Input 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: + description: The name of the new design. + default: 'Duplicate: ' + editor: + type: string + description: The editor used in the UI. + enum: + - code + - design + example: + name: 'Ahoy, Cake or Pie Cafe!' + editor: design + contact-details3: + title: contact-details3 + type: object + properties: + id: + type: string + first_name: + type: string + last_name: + type: string + unique_name: + type: string + email: + type: string + alternate_emails: 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. + type: string + address_line_1: + type: string + address_line_2: + type: string + city: + type: string + state_province_region: + type: string + country: + type: string + postal_code: + type: string + phone_number: + type: string + whatsapp: + type: string + line: + type: string + facebook: + type: string + list_ids: + type: array + items: + type: string + segment_ids: + type: array + items: + type: string + custom_fields: + type: object + created_at: + type: string + updated_at: + type: string + _metadata: + $ref: '#/definitions/selfmetadata' required: - - name - - conditions - example: - name: Last Name Miller - list_id: 4 - conditions: - - field: last_name - value: Miller - operator: eq - and_or: '' - - field: last_clicked - value: 01/02/2015 - operator: gt - and_or: and - - field: clicks.campaign_identifier - value: '513' - operator: eq - and_or: or - recipient_count: 1234 - api_key_name_id: - title: API Key Name and ID + - id + - list_ids + - segment_ids + - created_at + - updated_at + transactional-template-warning: + title: Warning type: object properties: - api_key_id: + message: type: string - description: 'The ID of your API Key. ' - name: - type: string - description: The name of your API Key. - example: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - advanced_stats_opens: - title: 'Stats: Advanced Stats with Opens' + description: Warning message for the user + example: + message: A sample warning message. + errors: + title: Errors type: object + description: 'If the request is incorrect, an array of errors will be returned.' properties: - date: - type: string - description: The date that the events occurred. - stats: + errors: type: array - description: The statistics of the email events. items: type: object properties: - type: - type: string - description: The type of segmentation. - name: + parameter: 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. + description: The parameter in the request body that is incorrect. + message: + type: + - string + - 'null' + description: A description of what is wrong with the field passed in the request. + field: + type: + - string + - 'null' required: - - type - - name - - metrics + - parameter + - message required: - - date - - stats - mail_settings_template: - title: '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. - example: - enabled: false - html_content: | -

<% body %>Example

- ip_warmup_response: - title: 'IP Warmup: IP' - type: array - items: - type: object - properties: - ip: - type: string - description: The IP address. - start_date: - type: integer - description: A Unix timestamp indicating when the IP address was entered into warmup mode. - required: - - ip - - start_date - example: - - ip: 0.0.0.0 - start_date: 1409616000 - advanced_stats_mailbox_provider: - title: 'Stats: Advanced Stats for Mailbox Provider' + - errors + singlesends-response: + title: singlesends-response type: object properties: - date: - type: string - description: The date that the events occurred. - stats: + results: type: array - description: The statistics of the email events. items: type: object properties: - type: + id: type: string - description: The type of segmentation. - name: + description: This is the ID of the Single Dend you require stats for. + format: uuid + ab_variation: 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. + default: all + description: 'This is the A/B variation of the Single Send stat returned. If the `group_by` parameter doesn''t include `ab_variation` in the request, then the value is "all".' + format: uuid + ab_phase: + type: string + default: all + description: 'This is the A/B phase of the Single Send stat returned. If the `group_by` parameter doesn''t include `ab_phase` in the request, then the value is "all".' + enum: + - send + - test + - all + aggregation: + type: string + description: This describes the time unit to which the stat is rolled up. It is based on the `aggregated_by` parameter included in the request. It can be "total" or the date (in YYYY-MM-DD format) the stats are for. + default: total + stats: + $ref: '#/definitions/metrics' required: - - type - - name - - metrics + - id + - ab_variation + - ab_phase + _metadata: + $ref: '#/definitions/metadata' required: - - date - - stats - 'global:ErrorResponse': - title: 'Global: Error Response' + - results + - _metadata + automations-response: + title: automations-response type: object properties: - errors: + results: type: array items: type: object properties: - field: - type: - - string - - 'null' - description: The field that generated the error. - message: + id: + type: string + description: This is the ID of the Automation you are requesting stats for. + format: uuid + aggregation: type: string - description: The error message. + description: This describes the time unit to which the stat is rolled up. It is based on the `aggregated_by` parameter included in the request. It can be "total" or the date (in YYYY-MM-DD format) the stats are for. + default: total + step_id: + type: string + description: This is the ID of the step if the stats were requested to be grouped by `step_id`. + default: all + stats: + $ref: '#/definitions/metrics' required: - - message - example: - errors: - - field: field_name - message: Some message here - contactdb_custom_field_with_id: - title: ContactDB Custom field schema with ID. - allOf: - - $ref: '#/definitions/contactdb_custom_field' - - type: object - properties: - id: - type: number - description: The ID of the custom field. - monitor: - title: Create monitor settings request + - id + - aggregation + - step_id + _metadata: + $ref: '#/definitions/metadata' + required: + - results + metrics: + title: metrics 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. ' + bounce_drops: + type: integer + bounces: + type: integer + clicks: + type: integer + delivered: + type: integer + invalid_emails: + type: integer + opens: + type: integer + requests: + type: integer + spam_report_drops: + type: integer + spam_reports: + type: integer + unique_clicks: + type: integer + unique_opens: + type: integer + unsubscribes: + type: integer required: - - email - - frequency - example: - email: example@example.com - frequency: 50000 - errors: - title: Error Schema + - bounce_drops + - bounces + - clicks + - delivered + - invalid_emails + - opens + - requests + - spam_report_drops + - spam_reports + - unique_clicks + - unique_opens + - unsubscribes + singlesend_search: + title: singlesend_search type: object properties: - errors: + name: + type: string + minLength: 1 + maxLength: 100 + description: leading and trailing wildcard search on name of the Single Send + status: type: array + description: current status of the Single Send + uniqueItems: true items: - type: object - properties: - field: - type: - - 'null' - - string - description: The field that has the error. - message: - type: string - description: The message the API caller will receive. - ip_pool: - title: 'IP Pools: Pool' + type: string + enum: + - draft + - scheduled + - triggered + categories: + type: array + description: 'categories to associate with this Single Send, match any single send that has at least one of the categories' + uniqueItems: true + items: + type: string + singlesend_request: + title: singlesend_request type: object properties: name: type: string - description: The name of the IP pool. - maxLength: 64 + minLength: 1 + maxLength: 100 + description: The name of the Single Send. + categories: + type: array + uniqueItems: true + maxItems: 10 + description: The categories to associate with this Single Send. + items: + type: string + send_at: + type: string + format: date-time + description: The ISO 8601 time at which to send the Single Send — this must be set for a future time. + send_to: + type: object + properties: + list_ids: + type: array + description: The recipient List IDs that will receive the Single Send. + maxItems: 10 + items: + type: string + format: uuid + segment_ids: + type: array + description: The recipient Segment IDs that will receive the Single Send. + maxItems: 10 + items: + type: string + format: uuid + all: + type: boolean + description: 'Set to `true` to send to All Contacts. If set to `false`, at least one `list_ids` or `segment_ids` value must be provided before the Single Send is scheduled to be sent to recipients.' + default: false + email_config: + type: object + properties: + subject: + type: string + description: The subject line of the Single Send. Do not include this field when using a `design_id`. + html_content: + type: string + description: The HTML content of the Single Send. Do not include this field when using a `design_id`. + plain_content: + type: string + description: The plain text content of the Single Send. Do not include this field when using a `design_id`. + generate_plain_content: + type: boolean + description: 'If set to `true`, `plain_content` is always generated from `html_content`. If set to false, `plain_content` is not altered.' + default: true + design_id: + type: string + description: 'A `design_id` can be used in place of `html_content`, `plain_content`, and/or `subject`. You can retrieve a design''s ID from the ["List Designs" endpoint](https://sendgrid.api-docs.io/v3.0/designs-api/list-designs) or by pulling it from the design''s detail page URL in the Marketing Campaigns App.' + editor: + type: string + enum: + - code + - design + description: The editor — `"design"` or `"code"` — used to modify the Single Send's design in the Marketing Campaigns App. + default: code + suppression_group_id: + type: + - integer + - 'null' + description: The ID of the Suppression Group to allow recipients to unsubscribe — you must provide this or the `custom_unsubscribe_url`. + custom_unsubscribe_url: + type: + - string + - 'null' + description: The URL allowing recipients to unsubscribe — you must provide this or the `suppression_group_id`. + format: uri + sender_id: + type: + - integer + - 'null' + description: 'The ID of the verified Sender. You can retrieve a verified Sender''s ID from the ["Get Verified Senders" endpoint](https://sendgrid.api-docs.io/v3.0/sender-verification/get-verified-senders) or by pulling it from the Sender''s detail page URL in the SendGrid App.' + ip_pool: + type: + - string + - 'null' + description: The name of the IP Pool from which the Single Send emails are sent. required: - name - google_analytics_settings: - title: 'Settings: Google Analytics' + singlesend_schedule: + title: singlesend-schedule 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: + send_at: 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: + format: date-time + description: 'This is the ISO 8601 time at which to send the Single Send; must be in future, or the string "now"' + status: type: string - description: Any paid keywords. + enum: + - draft + - scheduled + - triggered + required: + - send_at + singlesend_warning: + title: singlesend_warning + type: object + properties: + warnings: + type: array + items: + type: object + properties: + message: + type: string + field: + type: string + warning_id: + type: string + to_email_array: + title: To Email Array + type: array + items: + type: object + properties: + email: + type: string + format: email + description: The intended recipient's email address. + name: + type: string + description: The intended recipient's name. + required: + - email example: - enabled: true - utm_source: sendgrid.com - utm_medium: email - utm_term: '' - utm_content: '' - utm_campaign: website - event_webhook_settings: - title: 'Webhooks: Event Webhook Settings' + - email: john_doe@example.com + name: John Doe + event-webhook-update-oauth-request: + title: 'Webhooks: Event Webhook Update with OAuth Request' type: object properties: enabled: @@ -17512,6 +26287,15 @@ definitions: dropped: type: boolean description: 'You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota' + oauth_client_id: + type: string + description: 'The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_token_url field.' + oauth_client_secret: + type: string + description: 'This secret is needed only once to create an access token. SendGrid will store this secret, allowing you to update your Client ID and Token URL without passing the secret to SendGrid again. When passing data in this field, you must also include the oauth_client_id and oauth_token_url fields.' + oauth_token_url: + type: string + description: 'The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id field.' required: - enabled - url @@ -17526,940 +26310,1384 @@ definitions: - open - click - dropped - user_profile: - title: 'User: Profile' - type: object - properties: - address: - type: string - description: The street address for this user profile. - address2: - type: string - description: An optional second line for the street address of this user profile. - city: - type: string - description: The city for the user profile. - company: - type: string - description: That company that this user profile is associated with. - country: - type: string - description: Th country of this user profile. - first_name: - type: string - description: The first name of the user. - last_name: - type: string - description: The last name of the user. - phone: - type: string - description: The phone number for the user. - state: - type: string - description: The state for this user. - website: - type: string - description: The website associated with this user. - zip: - type: string - description: The zip code for this user. - example: - address: '1451 Larimer Street, 3rd floor' - address2: '' - city: 'Denver, CO' - company: SendGrid - country: US - first_name: Matthew - last_name: Bernier - phone: '7208788003' - state: CO - website: 'http://sendgrid.com' - zip: '80202' - mail_settings_footer: - title: 'Mail Settings: Footer' + webhooks-event-webhook-request: + title: 'Webhooks: Event Webhook Request' type: object properties: enabled: type: boolean - description: Indicates if the Footer mail setting is currently enabled. - html_content: + description: Indicates if the event webhook is enabled. + url: type: string - description: The custom HTML content of your email footer. - plain_content: + description: The URL that you want the event webhook to POST to. + group_resubscribe: + type: boolean + description: Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event. + delivered: + type: boolean + description: Message has been successfully delivered to the receiving server. + group_unsubscribe: + type: boolean + description: 'Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event.' + spam_report: + type: boolean + description: Recipient marked a message as spam. + bounce: + type: boolean + description: Receiving server could not or would not accept message. + deferred: + type: boolean + description: Recipient's email server temporarily rejected message. + unsubscribe: + type: boolean + description: Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event. + processed: + type: boolean + description: Message has been received and is ready to be delivered. + open: + type: boolean + description: Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event. + click: + type: boolean + description: Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event. + dropped: + type: boolean + description: 'You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota' + oauth_client_id: type: string - description: The plain text content of your email footer. - example: - enabled: true - html_content: Example HTML content - plain_content: Example plain content - category_stats: - title: 'Stats: Category Stats' - type: object - properties: - date: + description: 'The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token. When passing data in this field, you must also include the oauth_token_url field.' + oauth_token_url: 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 + description: 'The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider. When passing data in this field, you must also include the oauth_client_id field.' required: - - date - example: - date: '2015-01-01' - stats: - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: cat1 - type: category - - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 0 - processed: 0 - requests: 0 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: cat2 - type: category - transactional_template: - title: 'Transactional Templates: Template' + - enabled + - url + - group_resubscribe + - delivered + - group_unsubscribe + - spam_report + - bounce + - deferred + - unsubscribe + - processed + - open + - click + - dropped + reply_to_email_object: + title: Reply_to Email Object type: object properties: - id: + email: type: string - description: The ID of the transactional template. + format: email + description: The email address where any replies or bounces will be returned. name: type: string - description: The name for the transactional template. - maxLength: 100 - versions: + description: A name or title associated with the `reply_to` email address. + required: + - email + example: + email: jane_doe@example.com + name: Jane Doe + automations-link-stats-response: + title: automations-link-stats-response + type: object + properties: + results: type: array - description: The different versions of this transactional template. + default: '' + description: '' items: - $ref: '#/definitions/transactional_template_version' + type: object + properties: + url: + type: string + description: 'This is the URL of the link clicked. If `{{custom_fields}}` are part of the URL, they will be included.' + format: uri + url_location: + type: integer + description: This is the location of the link clicked in each Automation step. Links are located according to their position within the message; the topmost link has index `0`. + minimum: 0 + step_id: + type: string + description: This is the ID of the step if the stats were requested to be grouped by `step_id`. + format: uuid + clicks: + type: integer + minimum: 1 + description: The number of clicks on this particular link. + required: + - url + - step_id + - clicks + total_clicks: + type: integer + _metadata: + $ref: '#/definitions/link-tracking-metadata' required: - - id - - name - parse-setting: - title: Parse Setting + - results + - total_clicks + - _metadata + link-tracking-metadata: + title: link tracking metadata type: object properties: - url: + prev: type: string - description: The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL. - hostname: + format: uri + description: 'The URL of the previous page of results. If this field isn''t present, you''re at the start of the list.' + self: type: string - description: 'A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, parse.yourdomain.com.' - spam_check: - type: boolean - description: Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain. - send_raw: - type: boolean - description: 'Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to "false", SendGrid will send a JSON payload of the content of your email. ' - example: - url: 'http://email.myhostname.com' - hostname: myhostname.com - spam_check: false - send_raw: true - contactdb_list: - title: ContactDB lists + format: uri + description: The URL of the current page of results. + next: + type: string + format: uri + description: 'The URL of the next page of results. If this field isn''t present, you''re at the end of the list.' + count: + type: number + description: 'The number of items in the entire list, i.e., across all pages.' + singlesends-link-stats-response: + title: singlesends-link-stats-response type: object properties: - id: + results: + type: array + default: index + description: This is the index of the link's location in the email contents. + items: + type: object + properties: + url: + type: string + description: 'This is the URL of the link clicked. If `{{custom_fields}}` are part of the URL, they will be included.' + format: uri + url_location: + type: integer + description: 'This is the location of the link clicked in each Single Send A/B variation, or in the Single Send itself if there are no variations. Links are numbered from the top down; the topmost link is index `0`.' + minimum: 0 + ab_variation: + type: string + description: This is the A/B variation of the Single Send stat returned. It is set to `"all"` if the `ab_variation` query parameter was not set in the request and `group_by` doesn't contain `ab_variation`. + format: uuid + ab_phase: + type: string + description: 'This is the A/B phase of the Single Send stat returned. If the `ab_phase` query parameter was not provided, it will return `"all"`.' + enum: + - send + - test + - all + clicks: + type: integer + minimum: 1 + description: the number of clicks on this particular link + required: + - url + - ab_variation + - ab_phase + - clicks + _metadata: + $ref: '#/definitions/link-tracking-metadata' + total_clicks: type: integer - description: The reference ID of your list. - name: + required: + - results + - _metadata + domain-authentication-200-response: + title: Domain Authentication 200 Response + type: array + items: + allOf: + - $ref: '#/definitions/authentication::domain' + - type: object + properties: + subusers: + type: array + items: + type: object + properties: + user_id: + type: integer + description: The ID of the subuser that this authenticated domain will be associated with. + username: + type: string + description: The username of the subuser that this authenticated domain is associated with. + last_validation_attempt_at: + type: integer + description: A Unix epoch timestamp representing the last time of a validation attempt. + example: + - id: 1 + user_id: 7 + subdomain: mail + domain: example.com + username: jane@example.com + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + legacy: false + automatic_security: true + valid: true + dns: + mail_cname: + valid: true + type: cname + host: mail.example.com + data: u7.wl.sendgrid.net + dkim1: + valid: true + type: cname + host: s1._domainkey.example.com + data: s1._domainkey.u7.wl.sendgrid.net + dkim2: + valid: true + type: cname + host: s2._domainkey.example.com + data: s2._domainkey.u7.wl.sendgrid.net + - id: 2 + user_id: 8 + subdomain: new + domain: example2.com + username: john@example2.com + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_cname: + valid: false + type: mx + host: news.example2.com + data: sendgrid.net + dkim1: + valid: false + type: txt + host: example2.com + data: k=rsa; t=s; p=publicKey + dkim2: + valid: false + type: txt + host: example2.com + data: k=rsa; t=s p=publicKey + abtest_summary: + title: abTest_summary + type: + - object + - 'null' + properties: + type: type: string - description: The name of your list. - recipient_count: + description: What differs between the A/B tests + enum: + - subject + - content + winner_criteria: + type: string + description: How the winner will be decided + enum: + - open + - click + - manual + test_percentage: type: integer - description: The count of recipients currently in the list. + description: What percentage of your recipient will be included in your A/B testing + duration: + type: string + description: How long the A/B Testing will last + winning_template_id: + type: string + description: Winner of the A/B Test + winner_selected_at: + type: + - string + - 'null' + description: When the winner was selected + expiration_date: + type: + - string + - 'null' + description: Last day to select an A/B Test Winner required: - - id - - name - - recipient_count - example: - id: 1 - name: listname - recipient_count: 0 - suppression_group: - title: 'Suppressions: Suppression Group' + - type + - winner_criteria + - test_percentage + - duration + - winning_template_id + - winner_selected_at + - expiration_date + singlesend_response_short: + title: singlesend_response_short 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: + format: uuid + name: type: string - description: A description of the suppression group. + minLength: 1 maxLength: 100 - last_email_sent_at: - type: 'null' - is_default: + description: name of the Single Send + abtest: + $ref: '#/definitions/abtest_summary' + status: + type: string + enum: + - draft + - scheduled + - triggered + description: current status of the Single Send + categories: + type: array + uniqueItems: true + maxItems: 10 + description: categories to associate with this Single Send + items: + type: string + send_at: + type: string + format: date-time + description: the ISO 8601 time at which to send the Single Send; must be in future + is_abtest: type: boolean - default: false - description: Indicates if this is the default suppression group. + description: true if the Single Send's AB Test functionality has been toggled on + updated_at: + type: string + description: the ISO 8601 time at which the Single Send was last updated + format: date-time + created_at: + type: string + description: the ISO 8601 time at which the Single Send was created + format: date-time required: - id - name - - description - mail_settings_bounce_purge: - title: 'Mail Settings: Bounce Purge' + - abtest + - status + - categories + - is_abtest + - updated_at + - created_at + cc_bcc_email_object: + title: CC BCC Email Object type: object properties: - enabled: + email: + type: string + format: email + description: The intended recipient's email address. + name: + type: string + description: The intended recipient's name. + required: + - email + example: + email: jane_doe@example.com + name: Jane Doe + verified-sender-request-schema: + title: Verified Sender Request Schema + type: object + properties: + nickname: + type: string + maxLength: 100 + from_email: + type: string + maxLength: 256 + format: email + from_name: + type: string + maxLength: 256 + reply_to: + type: string + maxLength: 256 + format: email + reply_to_name: + type: string + maxLength: 256 + address: + type: string + maxLength: 100 + address2: + type: string + maxLength: 100 + state: + type: string + maxLength: 2 + city: + type: string + maxLength: 150 + zip: + type: string + maxLength: 10 + country: + type: string + maxLength: 100 + required: + - nickname + - from_email + - reply_to + example: + nickname: Orders + from_email: orders@example.com + from_name: Example Orders + reply_to: orders@example.com + reply_to_name: Example Orders + address: 1234 Fake St + address2: PO Box 1234 + state: CA + city: San Francisco + country: USA + zip: '94105' + verified-sender-response-schema: + title: Verified Sender Response Schema + type: object + properties: + id: + type: integer + nickname: + type: string + from_email: + type: string + from_name: + type: string + reply_to: + type: string + reply_to_name: + type: string + address: + type: string + address2: + type: string + state: + type: string + city: + type: string + zip: + type: string + country: + type: string + verified: + type: boolean + locked: 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.' example: - enabled: false - soft_bounces: 1234 - hard_bounces: null - transactional_template_version: - title: 'Transactional Templates: Version' + id: 1234 + nickname: Example Orders + from_email: orders@example.com + from_name: Example Orders + reply_to: orders@example.com + reply_to_name: Example Orders + address: 1234 Fake St. + address2: PO Box 1234 + state: CA + city: San Francisco + country: USA + zip: '94105' + verified: true + locked: false + ip-access-response: + title: IP Access Response + type: object + properties: + result: + type: array + description: An array listing all of your allowed IPs. + items: + type: object + properties: + id: + type: integer + description: The ID of the allowed IP. + ip: + type: string + description: The allowed IP. + created_at: + type: integer + description: A Unix timestamp indicating when the IP was added to the allow list. + updated_at: + type: integer + description: A Unix timestamp indicating when the IPs allow status was most recently updated. + example: + result: + - id: 1 + ip: 192.168.1.1/32 + created_at: 1441824715 + updated_at: 1441824715 + - id: 2 + ip: 192.0.0.0/8 + created_at: 1441824715 + updated_at: 1441824715 + - id: 3 + ip: 192.168.1.3/32 + created_at: 1441824715 + updated_at: 1441824715 + stats-advanced-global-stats: + title: 'Stats: Advanced Global Stats' + allOf: + - $ref: '#/definitions/advanced_stats_clicks_opens' + - 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. + 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. + 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. + 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. + stats-advanced-stats-base-schema: + title: 'Stats: Advanced Stats Base 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 + full-segment: + title: full_segment + allOf: + - $ref: '#/definitions/segment_summary' + - type: object + properties: + contacts_sample: + type: array + items: + $ref: '#/definitions/contact_response' + query_json: + type: object + description: AST representation of the query DSL + required: + - contacts_sample + - $ref: '#/definitions/segment_write' + example: + id: 58567a46-305e-48d1-b4f8-a006c906920e + contacts_count: 9266921 + created_at: '2085-08-08T21:07:05.692Z' + sample_updated_at: '3407-09-25T04:25:02.140Z' + updated_at: '4431-05-07T22:23:22.352Z' + contacts_sample: + - contact_id: c1183ada-b784-49ac-9b1f-50e73578a6dc + primary_email: ft88@d.izxx + alternate_emails: + - yKDUP11FDch@QoU.vwy + - ZNSN5@czAMqPi.at + - 7wr51kFVVKlcBSH@DWxOueOZepetzBrku.qosk + - iib-ObtO7Fxz5@vLJPRIFKPOqJGCEqcIDab.ypn + first_name: est + last_name: eiusmod in laboris velit cupidatat + address_line_1: sunt aliqua + address_line_2: sit proident Lorem veniam labore + city: "\x9CȎţȸÛ\tč\vCŁ" + state_province_region: ut proident + postal_code: 30296612 + country: do reprehenderit qui + custom_fields: + custom_field_name2: in consectetur ut aliqua sint + custom_field_name1: esse + name: culpa + query_dsl: cillum eiusmod + parent_list_id: 2357714d-3d82-4c80-826c-b44a4147f81c + next_sample_update: '' + senders-id-request-body: + title: Senders ID Request Body type: object properties: - template_id: + nickname: 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: + description: A nickname for the sender identity. Not used for sending. + from: + type: object + required: + - email + - name + properties: + email: + type: string + description: This is where the email will appear to originate from for your recipient + name: + type: string + description: This is the name appended to the from email field. IE - Your name or company name. + reply_to: + type: object + properties: + email: + type: string + description: This is the email that your recipient will reply to. + name: + type: string + description: This is the name appended to the reply to email field. IE - Your name or company name. + required: + - email + address: type: string - description: Name of the new transactional template version. - html_content: + description: The physical address of the sender identity. + address_2: type: string - description: The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content. - plain_content: + description: Additional sender identity address information. + city: 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: + description: The city of the sender identity. + state: + type: string + description: The state of the sender identity. + zip: + type: string + description: The zipcode of the sender identity. + country: type: string - description: Subject of the new transactional template version. Must include <%subject%> tag. + description: The country of the sender identity. required: - - template_id - - active - - name - - html_content - - plain_content - - subject - mail_settings_bcc: - title: 'Mail Settings: BCC' + - nickname + - from + - address + - city + - country + enforced-tls-request-response: + title: Enforced TLS Request Response type: object properties: - email: - type: string - description: The email address that will be sent a blind carbon copy. - enabled: + require_tls: type: boolean - description: Indicates if the BCC setting is enabled. - example: - email: example@example.com - enabled: false - 'global:id': - title: 'Global: ID' - type: integer - credentials: - title: Credentials - type: object - properties: - permissions: - type: object + description: 'Indicates if you want to require your recipients to support TLS. ' + require_valid_cert: + type: boolean + description: Indicates if you want to require your recipients to have a valid certificate. + singlesend_response: + title: singlesend_response + allOf: + - $ref: '#/definitions/singlesend_request' + - type: object properties: - api: + id: type: string - mail: + format: uuid + status: type: string - web: + enum: + - draft + - scheduled + - triggered + description: current status of the Single Send + updated_at: type: string - username: - type: string - example: - address: 1234 example street - address2: null - city: Denver - company: Company name - country: US - email: example@example.com - first_name: Example - last_name: User - phone: (555) 555-5555 - state: CO - zip: '55555' - subuser_stats: - title: subuser_stats - type: object - properties: - date: - type: string - description: The date the statistics were gathered. - stats: - type: array - description: The list of statistics. - items: - type: object - properties: - first_name: - type: string - description: The first name of the subuser. - last_name: - type: string - description: The last name of the subuser. - metrics: + description: the ISO 8601 time at which the Single Send was last updated + format: date-time + created_at: + type: string + description: the ISO 8601 time at which the Single Send was created + format: date-time + warnings: + type: array + items: 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. - name: - type: string - description: The username of the subuser. - type: - type: string - description: The type of account. - campaign_request: - title: Campaigns 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 - 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 - user_scheduled_send_status: - title: 'User: Scheduled Send status' + message: + type: string + field: + type: string + warning_id: + type: string + required: + - id + - status + - created_at + example: + name: Example API Created Single Send + id: 27c21bbf-a12c-440b-b8bf-c526975328ca + status: scheduled + created_at: '2020-05-18T17:28:27.272Z' + send_at: '2020-06-16T00:19:55.106Z' + categories: + - unique opens + email_config: + subject: '' + html_content: '' + plain_content: '' + generate_plain_content: true + editor: code + suppression_group_id: null + custom_unsubscribe_url: null + sender_id: null + ip_pool: null + send_to: + list_ids: + - f2fe66a1-43f3-4e3a-87b1-c6a600d805f0 + design-common-fields: + title: Design Common Fields allOf: - - $ref: '#/definitions/mail_batch_id' + - $ref: '#/definitions/design-duplicate-input' - type: object - description: The status of the scheduled send. properties: - status: + generate_plain_content: + type: boolean + description: 'If true, plain_content is always generated from html_content. If false, plain_content is not altered.' + default: true + subject: type: string - description: The status of the scheduled send. - enum: - - cancel - - pause - required: - - status - mail_settings_forward_spam: - title: 'Mail Settings: Forward Spam' + description: Subject of the Design. + maxLength: 5000 + categories: + type: array + description: The list of categories applied to the design + uniqueItems: true + maxItems: 10 + items: + type: string + maxLength: 255 + invalid-email: + title: Invalid Email type: object properties: + created: + type: integer + description: A Unix timestamp indicating when the email address was added to the invalid emails list. email: type: string - description: The email address where you would like the spam reports to be forwarded. - enabled: - type: boolean - description: Indicates if the Forward Spam setting is enabled. + description: The email address that was marked as invalid. + format: email + reason: + type: string + description: The reason that the email address was marked as invalid. example: - email: '' - enabled: true - contactdb_segments_with_id: - title: 'ContactDB:: Segments with ID' - allOf: - - type: object - properties: - id: - type: number - description: The ID of the segment. - required: - - id - - $ref: '#/definitions/contactdb_segments' - advanced_stats_country: - title: 'Stats: Advanced Stats with Clicks and Opens' + created: 1620141015 + email: invalid@example.com + reason: Mail domain mentioned in email address is unknown + email-activity-response-common-fields: + title: Email Activity Response Common Fields type: object properties: - date: + from_email: type: string - description: The date that the events occurred. - stats: + format: email + default: '' + description: The 'From' email address used to deliver the message. This address should be a verified sender in your Twilio SendGrid account. + msg_id: + type: string + description: A unique ID assigned to the message. This ID can be used to retrieve activity data for the specific message. + subject: + type: string + description: The email's subject line. + to_email: + type: string + format: email + description: The intended recipient's email address. + status: + type: string + description: The message's status. + enum: + - processed + - delivered + - not delivered + suppressions-request: + title: Suppressions Request Body + type: object + properties: + recipient_emails: type: array - description: The statistics of the email events. + description: The array of email addresses to add or find. 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 + type: string + format: email required: - - date - - stats - advanced_stats_clicks: - title: 'Stats: Advanced Stats with Clicks' + - recipient_emails + example: + recipient_emails: + - test1@example.com + - test2@example.com + suppression-group-request-base: + title: Suppression Group Request Base type: object properties: - date: + name: 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 - contactdb_recipient: - title: 'ContactDB: Recipient' + description: The name of your suppression group. Required when creating a group. + maxLength: 30 + description: + type: string + description: A brief description of your suppression group. Required when creating a group. + maxLength: 100 + is_default: + type: boolean + description: Indicates if you would like this to be your default suppression group. + sso-certificate-body: + title: Single Sign-On Certificate Body 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 - mail_settings_patch: - title: 'Mail Settings: Patch' + public_certificate: + type: string + description: This certificate is used by Twilio SendGrid to verify that SAML requests are coming from Okta. This is called the X509 certificate in the Twilio SendGrid UI. + id: + type: number + description: A unique ID assigned to the certificate by SendGrid. + not_before: + type: number + description: 'A unix timestamp (e.g., 1603915954) that indicates the time before which the certificate is not valid.' + not_after: + type: number + description: 'A unix timestamp (e.g., 1603915954) that indicates the time after which the certificate is no longer valid.' + intergration_id: + type: string + description: An ID that matches a certificate to a specific IdP integration. + example: + public_certificate: + id: 66138975 + not_before: 1621289880 + not_after: 1621289880 + intergration_id: b0b98502-9408-4b24-9e3d-31ed7cb15312 + sso-integration: + title: Single Sign-On Integration + allOf: + - $ref: '#/definitions/create-integration-request' + - type: object + properties: + last_updated: + type: number + description: A timestamp representing the last time the configuration was modified. + id: + type: string + description: A unique ID assigned to the configuration by SendGrid. + single_signon_url: + type: string + description: The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Audience URL when using SendGrid. + audience_url: + type: string + description: The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Single Sign-On URL when using SendGrid. + required: + - last_updated + create-integration-request: + title: Create Integration Request type: object properties: + name: + type: string + description: The name of your integration. This name can be anything that makes sense for your organization (eg. Twilio SendGrid) enabled: type: boolean - description: Indicates if the mail setting is enabled. - email: + description: Indicates if the integration is enabled. + signin_url: type: string - description: The email address of the recipient. - example: - enabled: true - email: email@example.com - mail_settings_forward_bounce: - title: 'Mail Settings: Forward Bounce' + description: The IdP's SAML POST endpoint. This endpoint should receive requests and initiate an SSO login flow. This is called the "Embed Link" in the Twilio SendGrid UI. + signout_url: + type: string + description: 'This URL is relevant only for an IdP-initiated authentication flow. If a user authenticates from their IdP, this URL will return them to their IdP when logging out.' + entity_id: + type: string + description: An identifier provided by your IdP to identify Twilio SendGrid in the SAML interaction. This is called the "SAML Issuer ID" in the Twilio SendGrid UI. + completed_integration: + type: boolean + description: Indicates if the integration is complete. + required: + - name + - enabled + - signin_url + - signout_url + - entity_id + sso-teammate-response: + title: Single Sign-On Teammate Response + allOf: + - $ref: '#/definitions/sso-teammate-common-fields' + - type: object + properties: + username: + type: string + description: This should be set to the Teammate's email address. + is_sso: + type: boolean + description: Indicates if the Teammate authenticates with SendGrid using SSO or with a username and password. + sso-teammate-request: + title: Single Sign-On Teammate Request + allOf: + - $ref: '#/definitions/sso-teammate-common-fields' + - type: object + properties: + scopes: + type: array + description: The permission scopes assigned to the Teammate. + items: + type: string + required: + - scopes + sso-teammates-patch-response: + title: Single Sign-On Teammates PATCH Response + allOf: + - $ref: '#/definitions/sso-teammate-response' + - type: object + properties: + address: + type: string + description: The Teammate’s street address. + address2: + type: string + description: 'The Teammate’s apartment number, suite number, or other secondary address information that is not part of the physical street address.' + city: + type: string + description: The Teammate's city. + company: + type: string + description: The Teammate’s company name. + country: + type: string + description: The Teammate’s country of residence. + email: + type: string + format: email + phone: + type: string + description: The Teammate’s stored phone number. + scopes: + type: array + description: The permission scopes assigned to the Teammate. + items: + type: string + state: + type: string + description: The Teammate’s state or province. + user_type: + type: string + description: 'A Teammate can be an “admin,” “owner,” or “teammate.” Each role is associated with the scope of the Teammate’s permissions.' + enum: + - admin + - owner + - teammate + website: + type: string + description: A website associated with the Teammate + zip: + type: string + description: The Teammate’s zip code. + sso-error-response: + title: SSO Error Response + type: array + items: + type: object + properties: + message: + type: string + field: + type: + - string + - 'null' + error_id: + type: string + click-tracking: + title: 'Settings: Click Tracking' type: object - properties: - email: - type: - - string - - 'null' - description: The email address that you would like your bounce reports forwarded to. + properties: + enable_text: + type: boolean + description: Indicates if click tracking is enabled for plain text emails. enabled: type: boolean - description: Indicates if the bounce forwarding mail setting is enabled. + description: Indicates if click tracking is enabled or disabled. + required: + - enable_text + - enabled example: + enable_text: false enabled: false - email: null - contactdb_custom_field_with_id_value: - title: ContactDB Custom field schema. - allOf: - - $ref: '#/definitions/contactdb_custom_field_with_id' - - type: object - properties: - value: - type: - - string - - 'null' - description: The value of this recipient's custom field - contactdb_recipient_count: - title: 'ContactDB: Recipient Count' + sso-teammate-common-fields: + title: Single Sing-On Teammate Common Fields type: object properties: - recipient_count: - type: number - description: The count of recipients. + first_name: + type: string + description: The Teammate’s first name. + last_name: + type: string + description: The Teammate’s last name. + email: + type: string + format: email + description: The Teammate’s email address. This email address will also function as the Teammate’s username and must match the address assigned to the user in your IdP. This address cannot be changed after the Teammate is created. + is_admin: + type: boolean + description: Indicates if the Teammate has admin permissions. + is_read_only: + type: boolean + description: Indicates if the Teammate has read_only permissions. required: - - recipient_count + - first_name + - last_name + - email + spam-reports-response: + title: Spam Reports Response + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp that indicates when the recipient marked your message as spam. + email: + type: string + description: The email address of the recipient that marked your message as spam. + format: email + ip: + type: string + description: The IP address that the message was sent from. + required: + - created + - email + - ip example: - recipient_count: 1234 - subuser_post: - title: 'Subuser::POST' + - created: 1443651141 + email: user1@example.com + ip: 10.63.202.100 + - created: 1443651154 + email: user2@example.com + ip: 10.63.202.100 + blocks-response: + title: Blocks Response + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the email address was added to the blocks list. + email: + type: string + description: The email address that was added to the block list. + format: email + reason: + type: string + description: An explanation for the reason of the block. + status: + type: string + description: The status of the block. + required: + - created + - email + - reason + - status + example: + - created: 1443651154 + email: example@example.com + reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' + status: 4.0.0 + ip_pool_response: + title: 'IP Pools: Pool Resp' type: object properties: - username: + name: type: string - description: The username of the subuser. - user_id: - type: number - description: The user ID for this subuser. - email: + description: The name of the IP pool. + abbv-message: + title: Abbv. Message + type: object + properties: + from_email: type: string - description: The email address for this subuser. - format: email - signup_session_token: + msg_id: type: string - authorization_token: + subject: type: string - credit_allocation: - type: object - properties: - type: - type: string + to_email: + type: string + status: + type: string + enum: + - processed + - delivered + - not_delivered + opens_count: + type: integer + clicks_count: + type: integer + last_event_time: + type: string + description: iso 8601 format required: - - username - - user_id - - email + - from_email + - msg_id + - subject + - to_email + - status + - opens_count + - clicks_count + - last_event_time example: - username: example_subuser - user_id: 1234 - email: example@example.com - signup_session_token: '' - authorization_token: '' - credit_allocation: - type: unlimited - 'whitelabel::domain': - title: Whitelabel - Domain + from_email: from@test.com + msg_id: abc123 + subject: anim Duis sint veniam + to_email: test@test.com + status: processed + opens_count: 1 + clicks_count: 2 + last_event_time: '2017-10-13T18:56:21Z' + message: + title: Message 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: + from_email: type: string - description: The subdomain to use for this domain whitelabel. - domain: + pattern: '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b' + msg_id: type: string - description: The domain that this whitelabel is being created for. - username: + minLength: 5 + maxLength: 50 + pattern: '^[A-Za-z0-9]+' + subject: type: string - description: The username that this whitelabel will be associated with. - ips: + minLength: 3 + maxLength: 255 + to_email: + type: string + pattern: '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b' + status: + type: string + description: Quick summary of the status of a message + enum: + - processed + - not delivered + - delivered + template_id: + type: string + format: uuid + asm_group_id: + type: integer + minimum: 1 + teammate: + type: string + description: Teammate's username + minLength: 0 + maxLength: 64 + pattern: '^$|^[A-Za-z0-9]+' + api_key_id: + type: string + minLength: 3 + maxLength: 50 + pattern: '^[A-Za-z0-9]+' + events: type: array - description: The IPs to be included in the custom SPF record for this domain whitelabel. + description: List of events related to email message items: + title: Event type: object - 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. + properties: + event_name: + type: string + description: Name of event + enum: + - bounced + - opened + - clicked + - processed + - dropped + - delivered + - deferred + - spam_report + - unsubscribe + - group_unsubscribe + - group_resubscribe + processed: + description: Date of when event occurred + minimum: 1292453589 + maximum: 9999999999 + type: string + reason: + type: string + description: 'Explanation of what caused "bounced", "deferred", or "blocked". Usually contains error message from the server - e.g. message from gmail why mail was deferred' + maxLength: 1024 + attempt_num: + type: integer + description: 'Used with "deferred" events to indicate the attempt number out of 10. One "deferred" entry will exists under events array for each time a message was deferred with error message from the server. ' + minimum: 1 + maximum: 10 + url: + type: string + description: Used with "clicked" event to indicate which url the user clicked. + pattern: '^((http[s]?|ftp):\/)?\/?([^:\/\s]+)((\/\w+)*\/)([\w\-\.]+[^#?\s]+)(.*)?(#[\w\-]+)?$' + bounce_type: + type: string + description: Use to distinguish between types of bounces + enum: + - bounced + - blocked + - expired + http_user_agent: + type: string + description: Client recipient used to click or open message + mx_server: + type: string + description: For example mx.gmail.com + required: + - event_name + - processed + - url + - bounce_type + - http_user_agent + - mx_server + example: + event_name: bounced + processed: '2017-10-13T18:56:21Z' + reason: some reason + url: 'http://3LX,MU}N=B8''d,K}>bEma{l~!ad%peIF}y>qHfLPWQ$l9b\!6.1H?$Z9H"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0"Q/-4dV"Yk3QGg[(O86=Pf"e17K4''r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*ObEma{l~!ad%peIF}y>qHfLPWQ$l9b\!6.1H?$Z9H"il-_gZD>/JPYsGqH4x4_3v090TCtnFalXGFiAdooDxgrDAYNXShUywSxwYr8gKeyc/4sal4VJ3IxEWsG74V5MYQ0mz27jhy7n5DHsUtApQ6zXHS13uO5vYBlJHpJRfuT6/F5nIpkHre2w3eTtN7M6pg9V5stjnnsavKkzQxyTv15CMSDLFwR_BTZwofhWpyBU7B9ypYL79vT97N3LDZyoaM/fNsOLPIqfGBer_Mx9_StergbQYANyOmOSjR6pZof01ky/ZcNDhpu3CkSl4MTtQ3NMCX780pOKQ5SYIPigyvz9IC9WtrCNcOkTxdOPdY0_4MJU4EuTTPmGvO/14KaJCDjIjgrbIqpzuUEL5mET0t2VeVlwvtnOnlHaBE8sic20ze2E0Xt3ETqXyzVJRjLDKh/LWkW8OVp_xkLBCCW7LQngRukKcOiWjMXeCEhYI9HoZ0RsMEWZC8KzRaHc4OI0uXPD4M9pav1LGrI/_0t_RnBnfnqGKsBJr0kdQi/Y6QN_aeawIqX5hDNIU3MF/wWKVWLS0ZFbDfK6KVv5oAid83EpwKoazAMA8MTfEXvHQLO7k7XYWX1Il3eGXL6/wCA96I1SOabzJkZHo2HsFpIC/VBk52Lnpp0xtDH/OCdlQ5e4PpxXQeklp70LPOndr7QKSYEQNUc48n36ixvTjhgpgO8wHsFFYqGcuBMHg9oaCARppQomiQDWYuVPVDynJHdsM1_gWl4/NSs8Y9PL7DrQXOu0UiFRRE0TUsvgqyUgJzlGjUnRziyYeROO75D0K_3aTtbGbCmhaxecos40a1w0PDCNkFp1W/iHwY7922drhsoM6ShwqqwGpAh5HLuU6Q5gqyckeai6YN7HCh9DdHPhhJcatgtMHZDKfQUBVt9ecUlDgiCFF_OnRX/GpzttcsL8E2FoXL9_eAWvSqjodROqx7MZCA/ORdnR/IssPCYP1kTHTIL5mZxv4UGEpyNjUzt4GdSJJTm0nztltWDYX8_Ezl2JvpLVnGVTJxobb4yQIJhe3n64khbOFyFLKHWEniIolm/AxpZQYmseWlVqrIz3YXU59XaSbTTrdCHNhvwF1ogXiiggN6TZ2B3QY_mBEtAp/SD0ONPVqEUkTNAFWTgnnlv6ZIMdMbTw5uZwtFRlB7qDvQouml9kujGmRu6k7zZMTOwWowRNtpboLUcL2NzkVgK6N1Zi2vq/Nt4NJvM5_l1dpIIbwJv_CIcZQZOqPtRWULa2iVxfmJJQaqgLQPwSHQH1zuRJMhraEsPjqVQRC0pZpSt/24VBDN8y31Ye/y_ekWxMdZCvr978C/WrdcTi29kxjJLyT9BII7BsgT5vLuI2l7ntqRAhAUWMs/h9JR0i8RbX5OfB46q41/TfmSdgi97bCR2HfgflyypXwKhRfKYU2MVpu2Dd90WQUlm7hZV8dSfGusuMj/nPMpRVWcbnvlAdsehJCPbLv6n4qdLSPeoMBo32acAGgu1BwBG8JsBgbH43yYi5X7UdGRWKqm_ZbqaDEKH3ncU/uA8EOJb41VfGho4LUeOi1IeYwVAhFEyO6YbteYZecEubrNFZrWWjZUqhzouzY95TeWU8E4StCXVPKlYPiFiwUSX20kG0lVtDbAy/7u4f4x0cYlFOvI1UN1qoOExmNxnxzQQFeM5exWfW2JrRXq5e0UdAJr4q2o9Y_0WaGfhL/nP6Ei06YajDKr11dK5H0LX/9CGTC37HFZeopyopzP_7fvGFkqIRoGTS48pLaIFz3gwpQNlWXUFCsd/PnRlsqJ3SBQSgp_AQe2cP6iBNy2bJI8lkxwY5YVDDdjxusuCcafdjfs2aUa/4tr_iMnNBnd27GxjQI28_JGJlfbOaajVJOxuPMT4ELpYCfPiFjdSbJyE0/gCwtj0rgDKSLWJnOPJ5TAJ935gCqeIsBhOhfcZX413GdilBZRRYEjCVKfOuWzHZ3GW/8yjyk5e_WMNv5F6xggl07w90DBwpx/Q/iWfncqMuSfoeFeqHQkDL9F5W19j1cGuAcyfIYMAXztHXpgTKh9vZcsLYC7LcgKr4FQj3JjEvtnDG2PjcMjGF/MnbCRCz22Ho410_vE9M1Hpq0wdk_i5DbZKNoSwlPgey9URkpuX146TcDdsx_VWDenCepY5HwMr9CPOY9hzUs/c5AWeUMXk/gvsI81Jkv5rHpEnNBUZXYzfqkwQfffhmrc/StLCtzRRlja8dpsEWdkzoKR9Kdxq1qAs5f0sdrGjVRLTT_s1Q2P59zhA/QmS4bubi64cYot3gSIgdNnkjA2GjCp1ETVa548_U9B6boTKDVmaKJlVIDvqL84RC3WI7Er/8opi2lZ48W83Ur47BRh38oOnI0agrCyZz8bp1w_gfVRlSO8PS0i/l_/qxq5xpLbhPkdxVoyZVsNAZchfnmkIHyIk5IK6EUDXdMR21y6OvKW50ZbooAtk9ymynBj4dAYMsd25RV7FE1I1vRTsiDw52/.E5WC0Ymo2zn.qelSbhzr-4laArYiWP.dwJB6qm_6rs0Rm5UXYaYtUNbh76_jJp_X1xQUCDSgbr2KOkDU0"Q/-4dV"Yk3QGg[(O86=Pf"e17K4''r{)kicofHSXcMmP@>VF^`~4j4F*L/1]tD+Lw!WI!@]*OZm6C`M$u96}*O<% body %>Example

\n" + }, + "x-stoplight": { + "id": "mail_settings_template", + "name": "Mail Settings: Template", + "public": true } }, "ip_warmup_response": { @@ -31744,7 +35468,12 @@ "ip": "0.0.0.0", "start_date": 1409616000 } - ] + ], + "x-stoplight": { + "id": "ip_warmup_response", + "name": "IP Warmup: IP", + "public": true + } }, "monitor": { "title": "Create monitor settings request", @@ -31767,6 +35496,11 @@ "example": { "email": "example@example.com", "frequency": 50000 + }, + "x-stoplight": { + "id": "monitor", + "name": "Monitor Settings", + "public": true } }, "global_error_response_schema": { @@ -31810,6 +35544,11 @@ "message": "error message" } ] + }, + "x-stoplight": { + "id": "global_error_response_schema", + "name": "Global Error Response Schema", + "public": true } }, "advanced_stats_mailbox_provider": { @@ -31857,7 +35596,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "advanced_stats_mailbox_provider", + "name": "Stats: Advanced Stats for Mailbox Provider", + "public": true + } }, "contactdb_custom_field_with_id": { "title": "ContactDB Custom field schema with ID.", @@ -31874,7 +35618,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "contactdb_custom_field_with_id", + "name": "ContactDB: Custom Field with ID", + "public": true + } }, "ip_pool": { "title": "IP Pools: Pool", @@ -31888,7 +35637,12 @@ }, "required": [ "name" - ] + ], + "x-stoplight": { + "id": "ip_pool", + "name": "IP Pools: Pool", + "public": true + } }, "google_analytics_settings": { "title": "Settings: Google Analytics", @@ -31926,6 +35680,11 @@ "utm_term": "", "utm_content": "", "utm_campaign": "website" + }, + "x-stoplight": { + "id": "google_analytics_settings", + "name": "Settings: Google Analytics", + "public": true } }, "event-webhook-response": { @@ -32007,7 +35766,12 @@ "open", "click", "dropped" - ] + ], + "x-stoplight": { + "id": "event-webhook-response", + "name": "Webhooks: Event Webhook Response", + "public": true + } }, "user_profile": { "title": "User: Profile", @@ -32070,6 +35834,11 @@ "state": "CO", "website": "http://sendgrid.com", "zip": "80202" + }, + "x-stoplight": { + "id": "user_profile", + "name": "User: Profile", + "public": true } }, "mail_settings_footer": { @@ -32093,6 +35862,11 @@ "enabled": true, "html_content": "Example HTML content", "plain_content": "Example plain content" + }, + "x-stoplight": { + "id": "mail_settings_footer", + "name": "Mail Settings: Footer", + "public": true } }, "category_stats": { @@ -32261,6 +36035,11 @@ "type": "category" } ] + }, + "x-stoplight": { + "id": "category_stats", + "name": "Stats: Category Stats", + "public": true } }, "parse-setting": { @@ -32289,6 +36068,11 @@ "hostname": "myhostname.com", "spam_check": false, "send_raw": true + }, + "x-stoplight": { + "id": "parse-setting", + "name": "Parse Setting", + "public": true } }, "transactional_template": { @@ -32314,6 +36098,11 @@ "message": "Sample warning message" }, "generation": "legacy" + }, + "x-stoplight": { + "id": "transactional_template", + "name": "Transactional Templates: Template", + "public": true } }, "contactdb_list": { @@ -32342,6 +36131,11 @@ "id": 1, "name": "listname", "recipient_count": 0 + }, + "x-stoplight": { + "id": "contactdb_list", + "name": "ContactDB: List", + "public": true } }, "suppression_group": { @@ -32379,7 +36173,12 @@ "id", "name", "description" - ] + ], + "x-stoplight": { + "id": "suppression_group", + "name": "Suppressions: Suppression Group", + "public": true + } }, "mail_settings_bounce_purge": { "title": "Mail Settings: Bounce Purge", @@ -32408,6 +36207,11 @@ "enabled": false, "soft_bounces": 1234, "hard_bounces": null + }, + "x-stoplight": { + "id": "mail_settings_bounce_purge", + "name": "Mail Settings: Bounce Purge", + "public": true } }, "transactional_template_version_output": { @@ -32430,7 +36234,12 @@ { "$ref": "#/definitions/transactional-templates-version-output-lean" } - ] + ], + "x-stoplight": { + "id": "transactional_template_version_output", + "name": "Transactional Templates: Version Output", + "public": true + } }, "credentials": { "title": "Credentials", @@ -32466,11 +36275,21 @@ "phone": "(555) 555-5555", "state": "CO", "zip": "55555" + }, + "x-stoplight": { + "id": "credentials", + "name": "Credentials", + "public": true } }, "global:id": { "title": "Global: ID", - "type": "integer" + "type": "integer", + "x-stoplight": { + "id": "global:id", + "name": "Global: ID", + "public": true + } }, "mail_settings_forward_spam": { "title": "Mail Settings: Forward Spam", @@ -32488,6 +36307,11 @@ "example": { "email": "", "enabled": true + }, + "x-stoplight": { + "id": "mail_settings_forward_spam", + "name": "Mail Settings: Forward Spam", + "public": true } }, "campaign_request": { @@ -32610,6 +36434,11 @@ "html_content": "

Check out our summer line!

", "plain_content": "Check out our summer line!", "status": "Draft" + }, + "x-stoplight": { + "id": "campaign_request", + "name": "Campaigns Request", + "public": true } }, "subuser_stats": { @@ -32743,6 +36572,11 @@ "type": "subuser" } ] + }, + "x-stoplight": { + "id": "subuser_stats", + "name": "subuser_stats", + "public": true } }, "user_scheduled_send_status": { @@ -32772,6 +36606,11 @@ "example": { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", "status": "pause" + }, + "x-stoplight": { + "id": "user_scheduled_send_status", + "name": "User Scheduled Send status", + "public": true } }, "advanced_stats_clicks_opens": { @@ -32784,7 +36623,12 @@ { "$ref": "#/definitions/advanced_stats_opens" } - ] + ], + "x-stoplight": { + "id": "advanced_stats_clicks_opens", + "name": "Stats: Advanced Stats with Clicks and Opens", + "public": true + } }, "contactdb_segments_with_id": { "title": "ContactDB:: Segments with ID", @@ -32804,7 +36648,12 @@ { "$ref": "#/definitions/contactdb_segments" } - ] + ], + "x-stoplight": { + "id": "contactdb_segments_with_id", + "name": "ContactDB:: Segments with ID", + "public": true + } }, "advanced_stats_clicks": { "title": "Stats: Advanced Stats with Clicks", @@ -32819,6 +36668,11 @@ "type": "integer", "description": "The number of unique recipients who clicked links in your emails." } + }, + "x-stoplight": { + "id": "advanced_stats_clicks", + "name": "Stats: Advanced Stats with Clicks", + "public": true } }, "contactdb_recipient": { @@ -32895,6 +36749,11 @@ ] } } + }, + "x-stoplight": { + "id": "contactdb_recipient", + "name": "ContactDB: Recipient", + "public": true } }, "mail_settings_patch": { @@ -32913,6 +36772,11 @@ "example": { "enabled": true, "email": "email@example.com" + }, + "x-stoplight": { + "id": "mail_settings_patch", + "name": "Mail Settings: Patch", + "public": true } }, "mail_settings_forward_bounce": { @@ -32934,6 +36798,11 @@ "example": { "enabled": false, "email": null + }, + "x-stoplight": { + "id": "mail_settings_forward_bounce", + "name": "Mail Settings: Forward Bounce", + "public": true } }, "mail_batch_id": { @@ -32950,6 +36819,11 @@ ], "example": { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" + }, + "x-stoplight": { + "id": "mail_batch_id", + "name": "Mail Batch ID", + "public": true } }, "subuser_post": { @@ -32998,6 +36872,11 @@ "credit_allocation": { "type": "unlimited" } + }, + "x-stoplight": { + "id": "subuser_post", + "name": "Subuser::POST", + "public": true } }, "contactdb_recipient_count": { @@ -33014,6 +36893,11 @@ ], "example": { "recipient_count": 1234 + }, + "x-stoplight": { + "id": "contactdb_recipient_count", + "name": "ContactDB: Recipient Count", + "public": true } }, "authentication::domain": { @@ -33212,6 +37096,11 @@ "data": "s2._domainkey.u7.wl.sendgrid.net" } } + }, + "x-stoplight": { + "id": "authentication::domain", + "name": "Domain Authentication - Mandatory Subdomain", + "public": true } }, "contactdb_custom_field_with_id_value": { @@ -33232,7 +37121,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "contactdb_custom_field_with_id_value", + "name": "ContactDB: Custom Field with ID & Value", + "public": true + } }, "transactional_template_version_create": { "title": "Transactional Templates: Version Create", @@ -33298,6 +37192,11 @@ "subject": "aliquip nulla Ut", "editor": "design", "plain_content": "labore dolore" + }, + "x-stoplight": { + "id": "transactional_template_version_create", + "name": "Transactional Templates: Version Create", + "public": true } }, "transactional-templates-version-output-lean": { @@ -33352,6 +37251,11 @@ "type": "string", "description": "A Thumbnail preview of the template's html content." } + }, + "x-stoplight": { + "id": "transactional-templates-version-output-lean", + "name": "Transactional Templates: Version Output Lean", + "public": true } }, "transactional-templates-template-lean": { @@ -33403,6 +37307,11 @@ "generation": "legacy", "updated_at ": "2021-04-28 13:12:46", "versions": [] + }, + "x-stoplight": { + "id": "transactional-templates-template-lean", + "name": "Transactional Templates: Template Lean", + "public": true } }, "custom-fields-by-id": { @@ -33412,6 +37321,11 @@ "w1": "2002-10-02T15:00:00Z", "w33": 9.5, "e2": "Coffee is a beverage that puts one to sleep when not drank." + }, + "x-stoplight": { + "id": "custom-fields-by-id", + "name": "custom-fields-by-id", + "public": true } }, "custom-fields-by-name": { @@ -33421,6 +37335,11 @@ "birthday": "2002-10-02T15:00:00Z", "shoe_size": 9.5, "favoriteQuote": "Coffee is a beverage that puts one to sleep when not drank." + }, + "x-stoplight": { + "id": "custom-fields-by-name", + "name": "custom-fields-by-name", + "public": true } }, "contact-details": { @@ -33489,7 +37408,12 @@ "list_ids", "created_at", "updated_at" - ] + ], + "x-stoplight": { + "id": "contact-details", + "name": "contact-details", + "public": true + } }, "contact-import": { "title": "contact-import", @@ -33545,6 +37469,11 @@ "description": "The ISO8601 timestamp when the job was finished.", "type": "string" } + }, + "x-stoplight": { + "id": "contact-import", + "name": "contact-import", + "public": true } }, "single-contact-request": { @@ -33607,6 +37536,11 @@ } } } + }, + "x-stoplight": { + "id": "single-contact-request", + "name": "single contact request", + "public": true } }, "contact-export": { @@ -33666,7 +37600,12 @@ "created_at", "updated_at", "expires_at" - ] + ], + "x-stoplight": { + "id": "contact-export", + "name": "contact-export", + "public": true + } }, "contact-summary": { "title": "contact-summary", @@ -33710,7 +37649,12 @@ "list_ids", "created_at", "updated_at" - ] + ], + "x-stoplight": { + "id": "contact-summary", + "name": "contact-summary", + "public": true + } }, "contact-request": { "title": "contact-request", @@ -33776,7 +37720,12 @@ }, "required": [ "email" - ] + ], + "x-stoplight": { + "id": "contact-request", + "name": "contact-request", + "public": true + } }, "contact-details2": { "title": "contact-details2", @@ -33875,7 +37824,12 @@ "list_ids", "created_at", "updated_at" - ] + ], + "x-stoplight": { + "id": "contact-details2", + "name": "contact-details2", + "public": true + } }, "selfmetadata": { "title": "selfMetadata", @@ -33885,6 +37839,11 @@ "type": "string", "description": "A link to this object." } + }, + "x-stoplight": { + "id": "selfmetadata", + "name": "selfMetadata", + "public": true } }, "error": { @@ -33906,7 +37865,12 @@ }, "required": [ "message" - ] + ], + "x-stoplight": { + "id": "error", + "name": "error", + "public": true + } }, "link": { "title": "Link", @@ -33918,6 +37882,11 @@ "href": { "type": "string" } + }, + "x-stoplight": { + "id": "link", + "name": "Link", + "public": true } }, "metadata": { @@ -33943,6 +37912,11 @@ "type": "number", "description": "The number of items in the entire list, i.e., across all pages." } + }, + "x-stoplight": { + "id": "metadata", + "name": "metadata", + "public": true } }, "webhook": { @@ -33963,7 +37937,12 @@ "required": [ "url", "nonce" - ] + ], + "x-stoplight": { + "id": "webhook", + "name": "webhook", + "public": true + } }, "list": { "title": "list", @@ -33987,6 +37966,11 @@ "_metadata": { "$ref": "#/definitions/selfmetadata" } + }, + "x-stoplight": { + "id": "list", + "name": "list", + "public": true } }, "reserved_field_definitions_response": { @@ -34026,7 +38010,12 @@ "field_type": "Text", "read_only": true } - ] + ], + "x-stoplight": { + "id": "reserved_field_definitions_response", + "name": "reserved_field_definitions_response", + "public": true + } }, "custom_field_definitions_response": { "title": "custom_field_definitions_response", @@ -34058,6 +38047,11 @@ "id": "a1_D", "name": "custom_field_name", "field_type": "Date" + }, + "x-stoplight": { + "id": "custom_field_definitions_response", + "name": "custom_field_definitions_response", + "public": true } }, "segment_write": { @@ -34077,7 +38071,12 @@ "required": [ "name", "query_dsl" - ] + ], + "x-stoplight": { + "id": "segment_write", + "name": "segment_write", + "public": true + } }, "segment_summary": { "title": "segment_summary", @@ -34130,7 +38129,12 @@ "created_at", "sample_updated_at", "updated_at" - ] + ], + "x-stoplight": { + "id": "segment_summary", + "name": "segment_summary", + "public": true + } }, "segment_query_json": { "title": "segment_query_json", @@ -34259,6 +38263,11 @@ } } } + }, + "x-stoplight": { + "id": "segment_query_json", + "name": "segment_query_json", + "public": true } }, "contact_response": { @@ -34357,7 +38366,12 @@ "postal_code", "country", "custom_fields" - ] + ], + "x-stoplight": { + "id": "contact_response", + "name": "contact_response", + "public": true + } }, "TNE-senderID": { "title": "Sender ID Response Body", @@ -34408,7 +38422,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "TNE-senderID", + "name": "Sender ID Response Body", + "public": true + } }, "api-error": { "title": "error", @@ -34428,7 +38447,12 @@ "message", "field", "error_id" - ] + ], + "x-stoplight": { + "id": "api-error", + "name": "error", + "public": true + } }, "api-errors": { "title": "errors", @@ -34440,6 +38464,11 @@ "$ref": "#/definitions/api-error" } } + }, + "x-stoplight": { + "id": "api-errors", + "name": "errors", + "public": true } }, "_metadata": { @@ -34462,6 +38491,11 @@ "type": "integer", "minimum": 0 } + }, + "x-stoplight": { + "id": "_metadata", + "name": "_metadata", + "public": true } }, "design-input": { @@ -34499,6 +38533,11 @@ "subject": "Getting Started", "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n
\n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n
\n \n \n \n \n \n
\n \n \n \n
\n

\n
\n \n \n \n \n \n
Ahoy, World!

{{Sender_Name}}

{{Sender_Address}}, {{Sender_City}}, {{Sender_State}} {{Sender_Zip}}

Unsubscribe - Unsubscribe Preferences

\n \n
\n
\n
\n
\n
\n \n ", "plain_content": "Ahoy, World!\n\n{{Sender_Name}}\n\n{{Sender_Address}} , {{Sender_City}} , {{Sender_State}} {{Sender_Zip}}\n\nUnsubscribe ( {{{unsubscribe}}} ) - Unsubscribe Preferences ( {{{unsubscribe_preferences}}} )" + }, + "x-stoplight": { + "id": "design-input", + "name": "Design Input", + "public": true } }, "design-output": { @@ -34510,7 +38549,12 @@ { "$ref": "#/definitions/design-input" } - ] + ], + "x-stoplight": { + "id": "design-output", + "name": "Design Output", + "public": true + } }, "design-output-summary": { "title": "Design Output - Summary", @@ -34592,6 +38636,11 @@ "self": "https://api.sendgrid.com/v3/designs?page_token=vHdvHCg0w1F-TmWJcPNpTEnFY2aPEmRBHONwOgZ6TgJbX2_I", "count": 3 } + }, + "x-stoplight": { + "id": "design-output-summary", + "name": "Design Output - Summary", + "public": true } }, "design-duplicate-input": { @@ -34615,6 +38664,11 @@ "example": { "name": "Ahoy, Cake or Pie Cafe!", "editor": "design" + }, + "x-stoplight": { + "id": "design-duplicate-input", + "name": "Design Duplicate Design Input", + "public": true } }, "contact-details3": { @@ -34703,7 +38757,12 @@ "segment_ids", "created_at", "updated_at" - ] + ], + "x-stoplight": { + "id": "contact-details3", + "name": "contact-details3", + "public": true + } }, "transactional-template-warning": { "title": "Warning", @@ -34716,6 +38775,11 @@ }, "example": { "message": "A sample warning message." + }, + "x-stoplight": { + "id": "transactional-template-warning", + "name": "Warning", + "public": true } }, "errors": { @@ -34755,7 +38819,12 @@ }, "required": [ "errors" - ] + ], + "x-stoplight": { + "id": "errors", + "name": "errors", + "public": true + } }, "singlesends-response": { "title": "singlesends-response", @@ -34810,7 +38879,12 @@ "required": [ "results", "_metadata" - ] + ], + "x-stoplight": { + "id": "singlesends-response", + "name": "singlesends-response", + "public": true + } }, "automations-response": { "title": "automations-response", @@ -34853,7 +38927,12 @@ }, "required": [ "results" - ] + ], + "x-stoplight": { + "id": "automations-response", + "name": "automations-response", + "public": true + } }, "metrics": { "title": "metrics", @@ -34909,7 +38988,12 @@ "unique_clicks", "unique_opens", "unsubscribes" - ] + ], + "x-stoplight": { + "id": "metrics", + "name": "metrics", + "public": true + } }, "singlesend_search": { "title": "singlesend_search", @@ -34942,6 +39026,11 @@ "type": "string" } } + }, + "x-stoplight": { + "id": "singlesend_search", + "name": "singlesend_search", + "public": true } }, "singlesend_request": { @@ -35063,7 +39152,12 @@ }, "required": [ "name" - ] + ], + "x-stoplight": { + "id": "singlesend_request", + "name": "singlesend_request", + "public": true + } }, "singlesend_schedule": { "title": "singlesend-schedule", @@ -35085,7 +39179,12 @@ }, "required": [ "send_at" - ] + ], + "x-stoplight": { + "id": "singlesend_schedule", + "name": "singlesend-schedule", + "public": true + } }, "singlesend_warning": { "title": "singlesend_warning", @@ -35108,6 +39207,11 @@ } } } + }, + "x-stoplight": { + "id": "singlesend_warning", + "name": "singlesend_warning", + "public": true } }, "to_email_array": { @@ -35135,7 +39239,12 @@ "email": "john_doe@example.com", "name": "John Doe" } - ] + ], + "x-stoplight": { + "id": "to_email_array", + "name": "To Email Array", + "public": true + } }, "event-webhook-update-oauth-request": { "title": "Webhooks: Event Webhook Update with OAuth Request", @@ -35220,7 +39329,12 @@ "open", "click", "dropped" - ] + ], + "x-stoplight": { + "id": "event-webhook-update-oauth-request", + "name": "Webhooks: Event Webhook Update with OAuth Request", + "public": true + } }, "webhooks-event-webhook-request": { "title": "Webhooks: Event Webhook Request", @@ -35301,7 +39415,12 @@ "open", "click", "dropped" - ] + ], + "x-stoplight": { + "id": "webhooks-event-webhook-request", + "name": "Webhooks: Event Webhook Request", + "public": true + } }, "reply_to_email_object": { "title": "Reply_to Email Object", @@ -35323,6 +39442,11 @@ "example": { "email": "jane_doe@example.com", "name": "Jane Doe" + }, + "x-stoplight": { + "id": "reply_to_email_object", + "name": "Reply_to Email Object", + "public": true } }, "automations-link-stats-response": { @@ -35374,7 +39498,12 @@ "results", "total_clicks", "_metadata" - ] + ], + "x-stoplight": { + "id": "automations-link-stats-response", + "name": "automations-link-stats-response", + "public": true + } }, "link-tracking-metadata": { "title": "link tracking metadata", @@ -35399,6 +39528,11 @@ "type": "number", "description": "The number of items in the entire list, i.e., across all pages." } + }, + "x-stoplight": { + "id": "link-tracking-metadata", + "name": "link tracking metadata", + "public": true } }, "singlesends-link-stats-response": { @@ -35459,7 +39593,12 @@ "required": [ "results", "_metadata" - ] + ], + "x-stoplight": { + "id": "singlesends-link-stats-response", + "name": "singlesends-link-stats-response", + "public": true + } }, "domain-authentication-200-response": { "title": "Domain Authentication 200 Response", @@ -35566,7 +39705,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "domain-authentication-200-response", + "name": "Domain Authentication 200 Response", + "public": true + } }, "abtest_summary": { "title": "abTest_summary", @@ -35627,7 +39771,12 @@ "winning_template_id", "winner_selected_at", "expiration_date" - ] + ], + "x-stoplight": { + "id": "abtest_summary", + "name": "abTest_summary", + "public": true + } }, "singlesend_response_short": { "title": "singlesend_response_short", @@ -35693,7 +39842,12 @@ "is_abtest", "updated_at", "created_at" - ] + ], + "x-stoplight": { + "id": "singlesend_response_short", + "name": "singlesend_response_short", + "public": true + } }, "cc_bcc_email_object": { "title": "CC BCC Email Object", @@ -35715,6 +39869,11 @@ "example": { "email": "jane_doe@example.com", "name": "Jane Doe" + }, + "x-stoplight": { + "id": "cc_bcc_email_object", + "name": "CC BCC Email Object", + "public": true } }, "verified-sender-request-schema": { @@ -35785,6 +39944,11 @@ "city": "San Francisco", "country": "USA", "zip": "94105" + }, + "x-stoplight": { + "id": "verified-sender-request-schema", + "name": "Verified Sender Request Schema", + "public": true } }, "verified-sender-response-schema": { @@ -35849,6 +40013,11 @@ "zip": "94105", "verified": true, "locked": false + }, + "x-stoplight": { + "id": "verified-sender-response-schema", + "name": "Verified Sender Response Schema", + "public": true } }, "ip-access-response": { @@ -35902,6 +40071,11 @@ "updated_at": 1441824715 } ] + }, + "x-stoplight": { + "id": "ip-access-response", + "name": "IP Access Response", + "public": true } }, "stats-advanced-global-stats": { @@ -35963,7 +40137,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "stats-advanced-global-stats", + "name": "Stats: Advanced Global Stats", + "public": true + } }, "stats-advanced-stats-base-schema": { "title": "Stats: Advanced Stats Base Schema", @@ -35988,6 +40167,11 @@ } } } + }, + "x-stoplight": { + "id": "stats-advanced-stats-base-schema", + "name": "Stats: Advanced Stats Base Schema", + "public": true } }, "full-segment": { @@ -36052,6 +40236,11 @@ "query_dsl": "cillum eiusmod", "parent_list_id": "2357714d-3d82-4c80-826c-b44a4147f81c", "next_sample_update": "" + }, + "x-stoplight": { + "id": "full-segment", + "name": "full_segment", + "public": true } }, "senders-id-request-body": { @@ -36126,7 +40315,12 @@ "address", "city", "country" - ] + ], + "x-stoplight": { + "id": "senders-id-request-body", + "name": "Senders ID Request Body", + "public": true + } }, "enforced-tls-request-response": { "title": "Enforced TLS Request Response", @@ -36144,6 +40338,11 @@ "example": { "require_tls": true, "require_valid_cert": true + }, + "x-stoplight": { + "id": "enforced-tls-request-response", + "name": "Enforced TLS Request Response", + "public": true } }, "singlesend_response": { @@ -36228,6 +40427,11 @@ "f2fe66a1-43f3-4e3a-87b1-c6a600d805f0" ] } + }, + "x-stoplight": { + "id": "singlesend_response", + "name": "singlesend_response", + "public": true } }, "design-common-fields": { @@ -36261,7 +40465,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "design-common-fields", + "name": "Design Common Fields", + "public": true + } }, "invalid-email": { "title": "Invalid Email", @@ -36285,6 +40494,11 @@ "created": 1620141015, "email": "invalid@example.com", "reason": "Mail domain mentioned in email address is unknown" + }, + "x-stoplight": { + "id": "invalid-email", + "name": "Invalid Email", + "public": true } }, "email-activity-response-common-fields": { @@ -36319,6 +40533,11 @@ "not delivered" ] } + }, + "x-stoplight": { + "id": "email-activity-response-common-fields", + "name": "Email Activity Response Common Fields", + "public": true } }, "suppressions-request": { @@ -36342,6 +40561,11 @@ "test1@example.com", "test2@example.com" ] + }, + "x-stoplight": { + "id": "suppressions-request", + "name": "Suppressions Request Body", + "public": true } }, "suppression-group-request-base": { @@ -36362,6 +40586,11 @@ "type": "boolean", "description": "Indicates if you would like this to be your default suppression group." } + }, + "x-stoplight": { + "id": "suppression-group-request-base", + "name": "Suppression Group Request Base", + "public": true } }, "sso-certificate-body": { @@ -36395,6 +40624,11 @@ "not_before": 1621289880, "not_after": 1621289880, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" + }, + "x-stoplight": { + "id": "sso-certificate-body", + "name": "Single Sign-On Certificate Body", + "public": true } }, "sso-integration": { @@ -36427,7 +40661,12 @@ "last_updated" ] } - ] + ], + "x-stoplight": { + "id": "sso-integration", + "name": "Single Sign-On Integration", + "public": true + } }, "create-integration-request": { "title": "Create Integration Request", @@ -36464,7 +40703,12 @@ "signin_url", "signout_url", "entity_id" - ] + ], + "x-stoplight": { + "id": "create-integration-request", + "name": "Create Integration Request", + "public": true + } }, "sso-teammate-response": { "title": "Single Sign-On Teammate Response", @@ -36485,7 +40729,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "sso-teammate-response", + "name": "Single Sign-On Teammate Response", + "public": true + } }, "sso-teammate-request": { "title": "Single Sign-On Teammate Request", @@ -36508,7 +40757,12 @@ "scopes" ] } - ] + ], + "x-stoplight": { + "id": "sso-teammate-request", + "name": "Single Sign-On Teammate Request", + "public": true + } }, "sso-teammates-patch-response": { "title": "Single Sign-On Teammates PATCH Response", @@ -36577,7 +40831,12 @@ } } } - ] + ], + "x-stoplight": { + "id": "sso-teammates-patch-response", + "name": "Single Sign-On Teammates PATCH Response", + "public": true + } }, "sso-error-response": { "title": "SSO Error Response", @@ -36598,6 +40857,11 @@ "type": "string" } } + }, + "x-stoplight": { + "id": "sso-error-response", + "name": "SSO Error Response", + "public": true } }, "click-tracking": { @@ -36620,6 +40884,11 @@ "example": { "enable_text": false, "enabled": false + }, + "x-stoplight": { + "id": "click-tracking", + "name": "Settings: Click Tracking", + "public": true } }, "sso-teammate-common-fields": { @@ -36652,7 +40921,12 @@ "first_name", "last_name", "email" - ] + ], + "x-stoplight": { + "id": "sso-teammate-common-fields", + "name": "Single Sing-On Teammate Common Fields", + "public": true + } }, "spam-reports-response": { "title": "Spam Reports Response", @@ -36691,7 +40965,12 @@ "email": "user2@example.com", "ip": "10.63.202.100" } - ] + ], + "x-stoplight": { + "id": "spam-reports-response", + "name": "Spam Reports Response", + "public": true + } }, "blocks-response": { "title": "Blocks Response", @@ -36731,7 +41010,12 @@ "reason": "error dialing remote address: dial tcp 10.57.152.165:25: no route to host", "status": "4.0.0" } - ] + ], + "x-stoplight": { + "id": "blocks-response", + "name": "Blocks Response", + "public": true + } }, "ip_pool_response": { "title": "IP Pools: Pool Resp", @@ -36741,6 +41025,14 @@ "type": "string", "description": "The name of the IP pool." } + }, + "example": { + "name": "sunt sint enim" + }, + "x-stoplight": { + "id": "ip_pool_response", + "name": "IP Pools: Pool Resp", + "public": true } }, "sender-id-request": { @@ -36818,6 +41110,11 @@ "state": "Colorado", "zip": "80202", "country": "United States" + }, + "x-stoplight": { + "id": "sender-id-request", + "name": "Sender ID Request", + "public": true } }, "abbv-message": { @@ -37162,5 +41459,3031 @@ "mx_server": "quis proident" } } + }, + "x-stoplight": { + "beforeScript": "function (ctx, request) {\n \n request.header.set('User-Agent', 'sendgrid/stoplightdocs');\n \n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint before scripts will not be run!\n SL.runEndpoint();\n \n //adds the Accept header to every request\n // request.header.set(\"accept\", \"application/json\")\n \n //request.header.set(\"foo\", \"bear\");\n //request.header.add(\"bar\", \"cat\");\n\n // if (request.url.query.get('accept')) {\n // request.header.set('Accept', 'this is a bad header');\n // }\n \n // if (request.url.query.get('behalf')) {\n // request.header.set('on-behalf-of', 'subuser2');\n // }\n \n // For example, adding ?mock=200 to a request url will enable mocking,\n // using the example endpoint response for the 200 status code.\n // var mock = request.url.query.get(\"mock\")\n // if (mock) {\n // ctx.mock.set(true, mock)\n //}\n \n // For example, adding the header X-Mock: 200 will enable mocking,\n // using the example endpoint response for the 200 status code.\n // var mock = request.header.get(\"X-Mock\");\n // if (mock) {\n\t // ctx.mock.set(true, mock);\n\t // ctx.learn.set(false);\n // }\n}", + "afterScript": "function (ctx, request, response) {\n // REMOVE WITH CAUTION. OR AT LEAST, JUST LEAVE IT COMMENTED OUT.\n // Removing this means your endpoint AFTER scripts will not be run!\n SL.runEndpoint();\n \n// if (response.body.get().count() > 1) {\n// request.hijack(200, 'application/json', {foo: 'bear'})\n// }\n\n \n //make this always available\n //SL.utilities.Audit_LogDataInResponse(ctx, request, response);\n \n //if (request.url.query.get('test')) {\n // SL.utilities.RunSpecifiedTests(ctx, request, response);\n //}\n \n // ELMER: Remove this, it logs only DELETE calls\n // if (JSON.parse(request.header.get('X-Mock')) == response.statusCode.get()) {\n // ctx.log.set(false);\n // } else {\n // ctx.log.set(true);\n //}\n}", + "version": { + "groups": { + "docs": [ + { + "divider": true, + "items": [], + "name": "Getting Started" + }, + { + "divider": false, + "items": [ + { + "_id": "api-authentication", + "type": "docTextSections" + }, + { + "_id": "api-authorization", + "type": "docTextSections" + }, + { + "_id": "api-requests", + "type": "docTextSections" + }, + { + "_id": "on-behalf-of", + "type": "docTextSections" + }, + { + "_id": "api-responses", + "type": "docTextSections" + }, + { + "_id": "api-rate-limits", + "type": "docTextSections" + }, + { + "_id": "api-errors", + "type": "docTextSections" + } + ], + "name": "How to use the SendGrid v3 API", + "description": "Welcome to SendGrid’s Web API v3! This API is RESTful, fully featured, easy to integrate with, and offers support in [7 different languages](https://sendgrid.com/docs/for-developers/sending-email/libraries/).\n\n## Libraries\n\n* [C#](https://github.com/sendgrid/sendgrid-csharp)\n* [Go](https://github.com/sendgrid/sendgrid-go)\n* [Java](https://github.com/sendgrid/sendgrid-java)\n* [Node.js](https://github.com/sendgrid/sendgrid-nodejs)\n* [PHP](https://github.com/sendgrid/sendgrid-php)\n* [Python](https://github.com/sendgrid/sendgrid-python)\n* [Ruby](https://github.com/sendgrid/sendgrid-ruby)" + }, + { + "description": "", + "items": [ + { + "_id": "POST_mail-send", + "type": "endpoints" + }, + { + "_id": "mail-send-limitations", + "type": "docTextSections" + }, + { + "_id": "mail-send-validation", + "type": "docTextSections" + }, + { + "_id": "mail-send-errors", + "type": "docTextSections" + }, + { + "_id": "cc_bcc_email_object", + "type": "schemas" + }, + { + "type": "schemas", + "_id": "from_email_object" + }, + { + "_id": "reply_to_email_object", + "type": "schemas" + }, + { + "_id": "to_email_array", + "type": "schemas" + }, + { + "_id": "mailSendErrors", + "type": "traits" + } + ], + "name": "Mail Send", + "divider": false + }, + { + "items": [ + { + "_id": "POST_mail-batch", + "type": "endpoints" + }, + { + "_id": "POST_user-scheduledsends", + "type": "endpoints" + }, + { + "_id": "GET_mail-batch-batchid", + "type": "endpoints" + }, + { + "_id": "GET_user-scheduledsends", + "type": "endpoints" + }, + { + "_id": "GET_user-scheduledsends-batchid", + "type": "endpoints" + }, + { + "_id": "PATCH_user-scheduledsends-batchid", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "DELETE_user-scheduledsends-batchid" + }, + { + "type": "schemas", + "_id": "mail_batch_id" + }, + { + "_id": "user_scheduled_send_status", + "type": "schemas" + }, + { + "_id": "cancelScheduledSendsErrors", + "type": "traits" + } + ], + "name": "Cancel Scheduled Sends", + "description": "The Cancel Scheduled Sends API allows you to cancel or pause the send of one or more emails using a batch ID.\n\nA `batch_id` groups multiple scheduled `mail/send` requests together with the same ID. You can cancel or pause all of the `mail/send` requests associated with a batch ID up to 10 minutes before the scheduled send time by passing a `batch_id` to the \"Cancel or puase a scheduled send\" endpoint.\n\nFor a guide on creating a `batch_id`, assigning it to a scheduled send, and modifying the send, see [\"Canceling a Scheduled Send\"](https://sendgrid.com/docs/for-developers/sending-email/stopping-a-scheduled-send/).\n\nThe Cancel Scheduled Sends API also make it possible to validate a `batch_id` and retrieve all scheduled sends as an array.\n\nWhen a batch is canceled, all messages associated with that batch will stay in your sending queue. When their `send_at` value is reached, they will be discarded.\n\nWhen a batch is paused, all messages associated with that batch will stay in your sending queue, even after their `send_at` value has passed. This means you can remove a `pause` status, and your scheduled send will be delivered once the pause is removed. Any messages left with a `pause` status that are more than 72 hours old will be discarded as Expired.", + "divider": false + }, + { + "divider": true, + "items": [], + "name": "Security" + }, + { + "description": "Your application, mail client, or website can all use API (Application Programming Interface) keys to authenticate access to SendGrid services. You can revoke an API key at any time without having to change your username and password, and an API key can be scoped to perform a limited number of actions.\n\nThere are 3 different types of API keys:\n\n* **Full Access** \nAllows the API key to access `GET`, `PATCH`, `PUT`, `DELETE` and `POST` endpoints for all parts of your account, excluding billing and Email Address Validation.\n* **Restricted Access** \nCustomizes levels of access for all parts of your account, excluding billing and Email Address Validation.\n* **Billing Access** \nAllows the API key to access billing endpoints for the account.\n\nYou must create your first API key using the [Twilio SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have a key with permissions to manage other keys, you can use the endpoints documented as part of this API.", + "divider": false, + "items": [ + { + "_id": "create-api-keys", + "type": "endpoints" + }, + { + "_id": "GET_apikeys", + "type": "endpoints" + }, + { + "_id": "GET_apikeys-apikeyid", + "type": "endpoints" + }, + { + "_id": "PATCH_apikeys-apikeyid", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "PUT_apikeys-apikeyid" + }, + { + "_id": "DELETE_apikeys-apikeyid", + "type": "endpoints" + }, + { + "_id": "api_key_name_id", + "type": "schemas" + }, + { + "_id": "api_key_name_id_scopes", + "type": "schemas" + }, + { + "_id": "apiKeysErrors", + "type": "traits" + } + ], + "name": "API Keys" + }, + { + "name": "API Key Permissions", + "description": null, + "divider": false, + "items": [ + { + "_id": "api-key-permissions", + "type": "docTextSections" + }, + { + "_id": "GET_scopes", + "type": "endpoints" + } + ] + }, + { + "items": [ + { + "_id": "GET_user-settings-enforcedtls", + "type": "endpoints" + }, + { + "_id": "PATCH_user-settings-enforcedtls", + "type": "endpoints" + }, + { + "_id": "enforced-tls-request-response", + "type": "schemas" + } + ], + "name": "Settings - Enforced TLS", + "description": "The Enforced TLS settings specify whether or not the recipient of your send is required to support TLS or have a valid certificate. The Enforced TLS endpoint supports retrieving and updating TLS settings.\n\nTwilio SendGrid sends all emails with [Opportunistic TLS](https://sendgrid.com/blog/myth-opportunistic-tls-email-privacy/) by default, meaning email is sent with TLS, and if the recipient's inbox provider does not accept the TLS encryption, we then send the message unencrypted.\n\nYou can optionally choose to enforce TLS encryption, meaning that if the recipient's inbox provider does not accept the TLS encryption, Twilio SendGrid drops the message and sends a block event with “TLS required but not supported” as the description.", + "divider": false + }, + { + "items": [ + { + "_id": "POST_accesssettings-whitelist", + "type": "endpoints" + }, + { + "_id": "GET_accesssettings-activity", + "type": "endpoints" + }, + { + "_id": "GET_accesssettings-whitelist", + "type": "endpoints" + }, + { + "_id": "GET_accesssettings-whitelist-ruleid", + "type": "endpoints" + }, + { + "_id": "DELETE_accesssettings-whitelist", + "type": "endpoints" + }, + { + "_id": "DELETE_accesssettings-whitelist-ruleid", + "type": "endpoints" + }, + { + "_id": "ip-access-response", + "type": "schemas" + } + ], + "name": "IP Access Management", + "divider": false, + "description": "IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API.\n\nThere is no limit to the number of IP addresses that you can allow.\n\n> It is possible to remove your own IP address from your list of allowed addresses, thus blocking your own access to your account. While we are able to restore your access, we do require thorough proof of your identify and ownership of your account. We take the security of your account very seriously, and wish to prevent any 'bad actors' from maliciously gaining access to your account.\n>\n> Your current IP is clearly displayed to help prevent you from accidentally removing it from the allowed addresses.\n\nFor more information, please see our [IP Access Management documentation](https://sendgrid.com/docs/ui/account-and-settings/ip-access-management/)." + }, + { + "divider": true, + "items": [], + "name": "Single Sign-On" + }, + { + "divider": false, + "items": [ + { + "_id": "sso-error-response", + "type": "schemas" + }, + { + "_id": "singleSignOnErrorsTrait", + "type": "traits" + } + ], + "name": "Single Sign-On Shared Models and Traits" + }, + { + "divider": false, + "items": [ + { + "_id": "POST_sso-certificates", + "type": "endpoints" + }, + { + "_id": "GET_sso-integrations-integrationid-certificates", + "type": "endpoints" + }, + { + "_id": "GET_sso-certificates-certid", + "type": "endpoints" + }, + { + "_id": "PATCH_sso-certificates-certid", + "type": "endpoints" + }, + { + "_id": "DELETE_sso-certificates-certid", + "type": "endpoints" + }, + { + "_id": "sso-certificate-body", + "type": "schemas" + } + ], + "name": "Certificates", + "description": ">Twilio SendGrid Single Sign-On is currently in beta. The following documentation and product interface may change as the product is improved.\n>\n>**Known limitations during beta** \nTwilio SendGrid SSO does not currently support granting an SSO user access to more than one Subuser without granting the SSO user administrator access at the top level of your Twilio SendGrid account.\n\nThe Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the [SSO section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sso).\n\nThe Certificates API allows you to create, modify, and delete SSO certificates. A SAML certificate allows your IdP and Twilio SendGrid to verify requests are coming from one another using the `public_certificate` and `integration_id` parameters.\n\nFor more information about managing SSO Certificates, see the [Twilio SendGrid SSO documentation](https://sendgrid.com/docs/ui/account-and-settings/sso/)." + }, + { + "divider": false, + "items": [ + { + "_id": "POST_sso-integrations", + "type": "endpoints" + }, + { + "_id": "GET_sso-integrations", + "type": "endpoints" + }, + { + "_id": "GET_sso-integrations-id", + "type": "endpoints" + }, + { + "_id": "PATCH_sso-integrations-id", + "type": "endpoints" + }, + { + "_id": "DELETE_sso-integrations-id", + "type": "endpoints" + }, + { + "_id": "create-integration-request", + "type": "schemas" + }, + { + "_id": "sso-integration", + "type": "schemas" + } + ], + "name": "Single Sign-On Settings", + "description": ">Twilio SendGrid Single Sign-On is currently in beta. The following documentation and product interface may change as the product is improved.\n>\n>**Known limitations during beta** \nTwilio SendGrid SSO does not currently support granting an SSO user access to more than one Subuser without granting the SSO user administrator access at the top level of your Twilio SendGrid account.\n\nThe Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the [SSO section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sso).\n\nThe Single Sign-On Settings API allows you to create, retrieve, modify, and delete SSO integrations for your Twilio SendGrid account. Each integration will correspond to a specific IdP such as Okta, Duo, or Microsoft Azure Active Directory.\n\n" + }, + { + "divider": false, + "items": [ + { + "_id": "POST_sso-teammates", + "type": "endpoints" + }, + { + "_id": "PATCH_sso-teammates-username", + "type": "endpoints" + }, + { + "_id": "sso-teammate-common-fields", + "type": "schemas" + }, + { + "_id": "sso-teammate-request", + "type": "schemas" + }, + { + "_id": "sso-teammate-response", + "type": "schemas" + }, + { + "_id": "sso-teammates-patch-response", + "type": "schemas" + } + ], + "name": "Single Sign-On Teammates", + "description": ">Twilio SendGrid Single Sign-On is currently in beta. The following documentation and product interface may change as the product is improved.\n>\n>**Known limitations during beta** \nTwilio SendGrid SSO does not currently support granting an SSO user access to more than one Subuser without granting the SSO user administrator access at the top level of your Twilio SendGrid account.\n\nThe Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the [SSO section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sso).\n\nThe Single Sign-On Teammates API allows you to add and modify SSO Teammates. SSO Teammates are the individual user accounts who will access your Twilio SendGrid account with SSO credentials.\n\nTo retrieve or delete an SSO Teammate, you will use the [Teammates API](https://sendgrid.api-docs.io/v3.0/teammates). \n\nFor more information about managing SSO Teammates, see the [Twilio SendGrid SSO documentation](https://sendgrid.com/docs/ui/account-and-settings/sso/#manage-users)." + }, + { + "divider": true, + "items": [], + "name": "Settings" + }, + { + "items": [ + { + "type": "endpoints", + "_id": "GET_mailsettings" + }, + { + "_id": "PATCH_mailsettings-addresswhitelist", + "type": "endpoints" + }, + { + "_id": "GET_mailsettings-addresswhitelist", + "type": "endpoints" + }, + { + "_id": "PATCH_mailsettings-footer", + "type": "endpoints" + }, + { + "_id": "GET_mailsettings-footer", + "type": "endpoints" + }, + { + "_id": "PATCH_mailsettings-forwardspam", + "type": "endpoints" + }, + { + "_id": "GET_mailsettings-forwardspam", + "type": "endpoints" + }, + { + "_id": "PATCH_mailsettings-template", + "type": "endpoints" + }, + { + "_id": "GET_mailsettings-template", + "type": "endpoints" + }, + { + "_id": "PATCH_mailsettings-bouncepurge", + "type": "endpoints" + }, + { + "_id": "GET_mailsettings-bouncepurge", + "type": "endpoints" + }, + { + "_id": "PATCH_mailsettings-forwardbounce", + "type": "endpoints" + }, + { + "_id": "GET_mailsettings-forwardbounce", + "type": "endpoints" + }, + { + "_id": "mail_settings_patch", + "type": "schemas" + }, + { + "_id": "mail_settings_address_whitelabel", + "type": "schemas" + }, + { + "_id": "mail_settings_footer", + "type": "schemas" + }, + { + "type": "schemas", + "_id": "mail_settings_forward_spam" + }, + { + "_id": "mail_settings_template", + "type": "schemas" + }, + { + "_id": "mail_settings_bounce_purge", + "type": "schemas" + }, + { + "_id": "mail_settings_forward_bounce", + "type": "schemas" + } + ], + "name": "Settings - Mail", + "description": "Mail Settings instruct SendGrid to apply specific settings to every email that you send over [SendGrid’s v3 API](https://sendgrid.api-docs.io/v3.0/mail-send/v3-mail-send) or [SMTP Relay](https://sendgrid.com/docs/for-developers/sending-email/building-an-x-smtpapi-header/). These settings include how to embed a custom footer, how to manage blocks, spam, and bounces, and more.\n\nFor a full list of Twilio SendGrid's Mail Settings, and what each one does, see our [Mail Settings documentation](https://sendgrid.com/docs/ui/account-and-settings/mail/).\n\nYou can also manage your Mail Settings in the [Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings)", + "divider": false + }, + { + "divider": false, + "items": [ + { + "_id": "PATCH_partnersettings-newrelic", + "type": "endpoints" + }, + { + "_id": "GET_partnersettings-newrelic", + "type": "endpoints" + }, + { + "_id": "GET_partnersettings", + "type": "endpoints" + }, + { + "_id": "partner_settings_new_relic", + "type": "schemas" + } + ], + "name": "Settings - Partner", + "description": "Elements that can be shared among more than one endpoint definition." + }, + { + "divider": false, + "items": [ + { + "_id": "POST_v3-teammates", + "type": "endpoints" + }, + { + "_id": "POST_v3-teammates-pending-token-resend", + "type": "endpoints" + }, + { + "_id": "GET_v3-teammates", + "type": "endpoints" + }, + { + "_id": "GET_v3-scopes-requests", + "type": "endpoints" + }, + { + "_id": "GET_v3-teammates-pending", + "type": "endpoints" + }, + { + "_id": "GET_v3-teammates-username", + "type": "endpoints" + }, + { + "_id": "PATCH_v3-scopes-requests-approve-id", + "type": "endpoints" + }, + { + "_id": "PATCH_v3-teammates-username", + "type": "endpoints" + }, + { + "_id": "DELETE_v3-scopes-requests-request_id", + "type": "endpoints" + }, + { + "_id": "DELETE_v3-teammates-pending-token", + "type": "endpoints" + }, + { + "_id": "DELETE_v3-teammates-username", + "type": "endpoints" + } + ], + "name": "Teammates", + "description": "Give and adjust account access." + }, + { + "name": "Alerts", + "items": [ + { + "_id": "POST_alerts", + "type": "endpoints" + }, + { + "_id": "GET_alerts", + "type": "endpoints" + }, + { + "_id": "GET_alerts-alertid", + "type": "endpoints" + }, + { + "_id": "DELETE_alerts-alertid", + "type": "endpoints" + }, + { + "_id": "PATCH_alerts-alertid", + "type": "endpoints" + } + ], + "divider": false, + "description": "Elements that can be shared among more than one endpoint definition." + }, + { + "items": [ + { + "_id": "user_profile", + "type": "schemas" + }, + { + "_id": "GET_user-profile", + "type": "endpoints" + }, + { + "_id": "PATCH_user-profile", + "type": "endpoints" + }, + { + "_id": "GET_user-account", + "type": "endpoints" + }, + { + "_id": "GET_user-email", + "type": "endpoints" + }, + { + "_id": "PUT_user-email", + "type": "endpoints" + }, + { + "_id": "GET_user-username", + "type": "endpoints" + }, + { + "_id": "PUT_user-username", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "GET_user-credits" + }, + { + "_id": "PUT_user-password", + "type": "endpoints" + } + ], + "name": "Users API", + "description": "Keeping your user profile up to date helps SendGrid verify who you are and share important communications with you.\n\nYou can learn more in the [SendGrid Account Details documentation.](https://sendgrid.com/docs/ui/account-and-settings/account/)", + "divider": false + }, + { + "items": [ + { + "type": "schemas", + "_id": "subuser" + }, + { + "_id": "subuser_post", + "type": "schemas" + }, + { + "type": "endpoints", + "_id": "GET_subusers" + }, + { + "_id": "POST_subusers", + "type": "endpoints" + }, + { + "_id": "PATCH_subusers-subusername", + "type": "endpoints" + }, + { + "_id": "DELETE_subusers-subusername", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "GET_subusers-reputations" + }, + { + "_id": "PUT_subusers-subusername-ips", + "type": "endpoints" + } + ], + "name": "Subusers API", + "description": "For more information about Subusers, visit the [longform Subusers documentation](https://sendgrid.com/docs/ui/account-and-settings/subusers/). You can also [manage Subusers in the SendGrid console](https://app.sendgrid.com/settings/subusers).", + "divider": false + }, + { + "divider": false, + "items": [ + { + "_id": "monitor", + "type": "schemas" + }, + { + "_id": "GET_subusers-subusername-monitor", + "type": "endpoints" + }, + { + "_id": "POST_subusers-subusername-monitor", + "type": "endpoints" + }, + { + "_id": "PUT_subusers-subusername-monitor", + "type": "endpoints" + }, + { + "_id": "DELETE_subusers-subusername-monitor", + "type": "endpoints" + } + ], + "name": "Subuser Monitor Settings", + "description": "Subuser monitor settings allow you to receive a sample of an outgoing message from a specific customer at a specific frequency of emails." + }, + { + "divider": false, + "items": [ + { + "_id": "subuser_stats", + "type": "schemas" + }, + { + "_id": "GET_subusers-subusername-stats-monthly", + "type": "endpoints" + }, + { + "_id": "GET_subusers-stats-monthly", + "type": "endpoints" + }, + { + "_id": "GET_subusers-stats-sums", + "type": "endpoints" + }, + { + "_id": "GET_subusers-stats", + "type": "endpoints" + } + ], + "name": "Subuser Statistics", + "description": "Subuser statistics enable you to view specific segments of your statistics, as compared to the general overview of all email activity on your account. SendGrid tracks your subusers' emails sent, bounces, and spam reports. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings.\n\nFor more information, see our [Subusers documentation](https://sendgrid.com/docs/ui/account-and-settings/subusers/). You can also access [Subuser Statistics in the SendGrid console](https://app.sendgrid.com/statistics/subuser)." + }, + { + "divider": true, + "items": [], + "name": "Deliverability" + }, + { + "name": "Link branding", + "items": [ + { + "_id": "POST_whitelabel-links", + "type": "endpoints" + }, + { + "_id": "POST_whitelabel-links-id-validate", + "type": "endpoints" + }, + { + "_id": "POST_whitelabel-links-linkid-subuser", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-links", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-links-id", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-links-default", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-links-subuser", + "type": "endpoints" + }, + { + "_id": "PATCH_whitelabel-links-id", + "type": "endpoints" + }, + { + "_id": "DELETE_whitelabel-links-id", + "type": "endpoints" + }, + { + "_id": "DELETE_whitelabel-links-subuser", + "type": "endpoints" + }, + { + "_id": "link_branding_200_response", + "type": "schemas" + } + ], + "description": "Email link branding (formerly \"Link Whitelabel\") allows all of the click-tracked links, opens, and images in your emails to be served from your domain rather than `sendgrid.net`. Spam filters and recipient servers look at the links within emails to determine whether the email looks trustworthy. They use the reputation of the root domain to determine whether the links can be trusted.\n\nYou can also manage link branding in the [Sender Authentication section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth).\n\nFor more information, please see our [Link Branding documentation](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/).", + "divider": false + }, + { + "name": "IP Warmup", + "items": [ + { + "_id": "POST_ips-warmup", + "type": "endpoints" + }, + { + "_id": "GET_ips-warmup", + "type": "endpoints" + }, + { + "_id": "GET_ips-warmup-ipaddress", + "type": "endpoints" + }, + { + "_id": "DELETE_ips-warmup-ipaddress", + "type": "endpoints" + }, + { + "type": "schemas", + "_id": "ip_warmup_response" + } + ], + "description": "IP warming is the practice of gradually increasing the volume of mail sent with a dedicated IP address according to a predetermined schedule. This gradual process helps to establish a reputation with ISPs (Internet Service Providers) as a legitimate email sender.\n\nSendGrid can automatically [warm up](https://sendgrid.com/docs/glossary/ip-warmup/) dedicated IP addresses by limiting the amount of mail that can be sent through them per hour. The limit determined by how long the IP address has been warming up. \n\nSee the [warmup schedule](https://sendgrid.com/docs/ui/sending-email/warming-up-an-ip-address/#automated-ip-warmup-hourly-send-schedule) to learn how SendGrid limits your email traffic for IPs in warmup.\n\nYou can also choose to use Twilio SendGrid's automated IP warmup for any of your IPs from the [\"IP Addresses\" settings menu in the Twilio SendGrid App](https://app.sendgrid.com/settings/ip_addresses).", + "divider": false + }, + { + "items": [ + { + "_id": "POST_whitelabel-ips", + "type": "endpoints" + }, + { + "_id": "POST_whitelabel-ips-id-validate", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-ips", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-ips-id", + "type": "endpoints" + }, + { + "_id": "DELETE_whitelabel-ips-id", + "type": "endpoints" + }, + { + "type": "schemas", + "_id": "reverse_dns" + } + ], + "name": "Reverse DNS", + "description": "Reverse DNS (formerly IP Whitelabel) allows mailbox providers to verify the sender of an email by performing a reverse DNS lookup upon receipt of the emails you send.\n\nReverse DNS is available for [dedicated IP addresses](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/) only.\n\nWhen setting up reverse DNS, Twilio SendGrid will provide an A Record (address record) for you to add to your DNS records. The A Record maps your sending domain to a dedicated Twilio SendGrid IP address.\n\nA Reverse DNS consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP address. Once Twilio SendGrid has verified that the appropriate A record for the IP address has been created, the appropriate reverse DNS record for the IP address is generated.\n\nYou can also manage your reverse DNS settings in the [Sender Authentication setion of the Twilio SendGrid App](https://app.sendgrid.com/settings/sender_auth).\n\nFor more about Reverse DNS, see [\"How to set up reverse DNS\"](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/) in the Twilio SendGrid documentation.", + "divider": false + }, + { + "divider": false, + "items": [ + { + "_id": "POST_validations-email", + "type": "endpoints" + } + ], + "name": "Email Address Validation", + "description": "**Email Address Validation is available to Email API Pro and Premier level accounts only. Prior to upgrading your account to Pro or Premier, you will not see the option to create an Email Validation API key. An Email Validation API key is separate from and in addition to your other keys, including a Full Access API key.**\n\nEmail Address Validation provides real-time detailed information on the validity of email addresses. You can integrate this validation process into your platform's signup form and customize the best use of email address validation for your use case.\n\nYou can use this API to:\n\n* Indicate to users that the address they have entered into a form is invalid.\n* Drop invalid email addresses from your database.\n* [Suppress invalid email addresses](https://sendgrid.com/docs/ui/sending-email/index-suppressions/#different-types-of-suppressions) from your sending to decrease your bounce rate.\n\nYou can learn more about enabling Email Validation in our [Email Validation documentation](https://sendgrid.com/docs/ui/managing-contacts/email-address-validation/).\n\nYou can also view your Email Validation results and metrics in the [Validation section of the Twilio SendGrid App](https://app.sendgrid.com/email_validation). Again, these settings are available only after upgrading your account to Pro or higher." + }, + { + "divider": false, + "items": [ + { + "_id": "POST_whitelabel-dns-email", + "type": "endpoints" + } + ], + "name": "Email CNAME records", + "description": "If you don't have access to modify your companies DNS records, you can email the records to a co-worker who does to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) and/or [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setups. This email includes a direct link to the DNS records. The link does expire, but the recipient doesn't need login access to your Twilio SendGrid account.\n" + }, + { + "items": [ + { + "_id": "POST_ips-pools", + "type": "endpoints" + }, + { + "_id": "POST_ips-pools-poolname-ips", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "GET_ips-pools" + }, + { + "_id": "GET_ips-pools-poolname", + "type": "endpoints" + }, + { + "_id": "PUT_ips-pools-poolname", + "type": "endpoints" + }, + { + "_id": "DELETE_ips-pools-poolname", + "type": "endpoints" + }, + { + "_id": "DELETE_ips-pools-poolname-ips-ip", + "type": "endpoints" + }, + { + "_id": "ip_pool", + "type": "schemas" + }, + { + "_id": "ip_pool_response", + "type": "schemas" + } + ], + "name": "IP Pools", + "description": "IP pools allow you to group your dedicated SendGrid IP addresses. For example, you could create separate one pool for your transactional email and another for your marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.\n\nIP pools can only be used with IP addresses for which you’ve set up a reverse DNS record.\n\nIf an IP pool is *not* specified for an email, it will use any IP available, including pooled addresses.\n\n**Each user can create up to 10 different IP pools.**", + "divider": false + }, + { + "items": [ + { + "_id": "POST_ips", + "type": "endpoints" + }, + { + "_id": "GET_ips-remaining", + "type": "endpoints" + }, + { + "_id": "GET_ips", + "type": "endpoints" + }, + { + "_id": "GET_ips-assigned", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "GET_ips-ipaddress" + } + ], + "name": "IP Addresses", + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false + }, + { + "description": "An authenticated domain allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Authenticating 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 get 2 TXT records and 1 MX record.\n\nDomain Authentication was formerly called \"Domain Whitelabel\".\n\nFor more information, please see [How to set up domain authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/).", + "divider": false, + "items": [ + { + "_id": "domain_authentication:domain_spf", + "type": "schemas" + }, + { + "_id": "authentication::domain", + "type": "schemas" + }, + { + "_id": "domain-authentication-200-response", + "type": "schemas" + }, + { + "type": "endpoints", + "_id": "GET_whitelabel-domains" + }, + { + "_id": "GET_whitelabel-domains-domainid", + "type": "endpoints" + }, + { + "_id": "POST_whitelabel-domains", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "PATCH_whitelabel-domains-domainid" + }, + { + "_id": "DELETE_whitelabel-domains-domainid", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-domains-default", + "type": "endpoints" + }, + { + "_id": "POST_whitelabel-domains-id-ips", + "type": "endpoints" + }, + { + "_id": "DELETE_whitelabel-domains-id-ips-ip", + "type": "endpoints" + }, + { + "_id": "POST_whitelabel-domains-id-validate", + "type": "endpoints" + }, + { + "_id": "GET_whitelabel-domains-subuser", + "type": "endpoints" + }, + { + "_id": "DELETE_whitelabel-domains-subuser", + "type": "endpoints" + }, + { + "_id": "POST_whitelabel-domains-domainid-subuser", + "type": "endpoints" + } + ], + "name": "Domain Authentication" + }, + { + "divider": false, + "items": [ + { + "_id": "GET_verifiedsenders-domains", + "type": "endpoints" + }, + { + "_id": "GET_verifiedsenders-stepscompleted", + "type": "endpoints" + }, + { + "_id": "POST_verifiedsenders", + "type": "endpoints" + }, + { + "_id": "GET_verifiedsenders-verify-token", + "type": "endpoints" + }, + { + "_id": "PATCH_verifiedsenders-id", + "type": "endpoints" + }, + { + "_id": "DELETE_verifiedsenders-id", + "type": "endpoints" + }, + { + "_id": "GET_verifiedsenders", + "type": "endpoints" + }, + { + "_id": "POST_verifiedsenders-resend-id", + "type": "endpoints" + }, + { + "_id": "verified-sender-request-schema", + "type": "schemas" + }, + { + "_id": "verified-sender-response-schema", + "type": "schemas" + } + ], + "name": "Sender Verification", + "description": "The Sender Verification API exposes multiple endpoints that allow you to programmatically manage the [Sender Identities](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) that are authorized to send email for your account.\nYou can also manage Sender Identities in the SendGrid app by selecting [**Sender Authentication** under **Settings** in the navigation bar](https://app.sendgrid.com/settings/sender_auth). For full app instructions, see [Sender Verification](https://sendgrid.com/docs/ui/sending-email/sender-verification/).\n\nThe Sender Verification API provides a RESTful interface for creating new Sender Identities, retrieving a list of existing Sender Identities, checking the status of a Sender Identity, updating a Sender Identity, and deleting a Sender Identity.\n \nThis API offers additional endpoints to check for domains known to implement DMARC, and resend verification emails to Sender Identities that have yet to complete the verification process." + }, + { + "divider": true, + "items": [], + "name": "Design Library" + }, + { + "divider": false, + "items": [ + { + "_id": "_metadata", + "type": "schemas" + }, + { + "_id": "api-error", + "type": "schemas" + }, + { + "_id": "api-errors", + "type": "schemas" + }, + { + "_id": "design-duplicate-input", + "type": "schemas" + }, + { + "_id": "design-common-fields", + "type": "schemas" + }, + { + "_id": "design-input", + "type": "schemas" + }, + { + "_id": "design-output-summary", + "type": "schemas" + }, + { + "_id": "design-output", + "type": "schemas" + }, + { + "_id": "designsQueryStrings", + "type": "traits" + }, + { + "_id": "POST-design", + "type": "endpoints" + }, + { + "_id": "POST-design", + "type": "endpoints" + }, + { + "_id": "LIST-designs", + "type": "endpoints" + }, + { + "_id": "GET-design", + "type": "endpoints" + }, + { + "_id": "POST-sendgrid-pre-built-design", + "type": "endpoints" + }, + { + "_id": "LIST-Sendgrid-Pre-built-designs", + "type": "endpoints" + }, + { + "_id": "GET-sendgrid-pre-built-design", + "type": "endpoints" + }, + { + "_id": "PUT-design", + "type": "endpoints" + }, + { + "_id": "DELETE-design", + "type": "endpoints" + } + ], + "name": "Designs API", + "description": "The Designs API offers the ability to manage assets stored in the Twilio SendGrid [Design Library](https://mc.sendgrid.com/design-library/my-designs).\n\nThe Design Library is a feature-rich email layout tool and media repository. You can [build designs for all your email needs](https://sendgrid.com/docs/ui/sending-email/working-with-marketing-campaigns-email-designs/), including Single Sends, Automations, and Dynamic Templates.\n\nYou can also duplicate and then modify one of the pre-built designs provided by Twilio SendGrid to get you started.\n\nThe Designs API provides a RESTful interface for creating new designs, retrieving a list of existing designs, duplicating or updating a design, and deleting a design." + }, + { + "divider": true, + "items": [], + "name": "New Marketing Campaigns" + }, + { + "divider": false, + "items": [ + { + "_id": "contact-import", + "type": "schemas" + }, + { + "_id": "single-contact-request", + "type": "schemas" + }, + { + "_id": "contact-export", + "type": "schemas" + }, + { + "_id": "contact-summary", + "type": "schemas" + }, + { + "_id": "contact-request", + "type": "schemas" + }, + { + "_id": "contact-details", + "type": "schemas" + }, + { + "_id": "contact-details2", + "type": "schemas" + }, + { + "_id": "contact-details3", + "type": "schemas" + }, + { + "_id": "PUT_mc-contacts", + "type": "endpoints" + }, + { + "_id": "DELETE_mc-contacts", + "type": "endpoints" + }, + { + "_id": "GET_mc-contacts-count", + "type": "endpoints" + }, + { + "_id": "POST_mc-contacts-exports", + "type": "endpoints" + }, + { + "_id": "GET_mc-contacts-id", + "type": "endpoints" + }, + { + "_id": "POST_mc-contacts-search", + "type": "endpoints" + }, + { + "_id": "GET_mc-contats", + "type": "endpoints" + }, + { + "_id": "PUT_mc-contacts-imports", + "type": "endpoints" + }, + { + "_id": "GET_marketing-contacts-imports-id", + "type": "endpoints" + }, + { + "_id": "GET_mc-contacts-exports-id", + "type": "endpoints" + }, + { + "_id": "GET_marketing-contacts-exports", + "type": "endpoints" + }, + { + "_id": "POST_marketing-contacts-batch", + "type": "endpoints" + }, + { + "_id": "POST_marketing-contacts-search-emails", + "type": "endpoints" + } + ], + "name": "Contacts" + }, + { + "divider": false, + "items": [ + { + "_id": "senders-id-request-body", + "type": "schemas" + }, + { + "_id": "TNE-senderID", + "type": "schemas" + }, + { + "_id": "POST_marketing-senders", + "type": "endpoints" + } + ], + "name": "Senders" + }, + { + "divider": false, + "items": [ + { + "_id": "list", + "type": "schemas" + }, + { + "_id": "POST_mc-lists", + "type": "endpoints" + }, + { + "_id": "GET_mc-lists-id-contacts-count", + "type": "endpoints" + }, + { + "_id": "GET_mc-lists-id", + "type": "endpoints" + }, + { + "_id": "GET_mc-lists", + "type": "endpoints" + }, + { + "_id": "PATCH_mc-lists-id", + "type": "endpoints" + }, + { + "_id": "DELETE_lists-id", + "type": "endpoints" + }, + { + "_id": "DELETE_mc-lists-id-contacts", + "type": "endpoints" + } + ], + "name": "Lists", + "description": "Lists are static collections of Marketing Campaigns contacts. This API allows you to interact with the list objects themselves. To add contacts to a list, you must use the [Contacts API](https://sendgrid.api-docs.io/v3.0/contacts).\n\nYou can also manage your lists using the [Contacts menu in the Marketing Campaigns UI](https://mc.sendgrid.com/contacts). For more information about lists and best practices for building them, see [\"Building your Contact List\"](https://sendgrid.com/docs/ui/managing-contacts/building-your-contact-list/)." + }, + { + "divider": false, + "items": [ + { + "_id": "custom-fields-by-name", + "type": "schemas" + }, + { + "_id": "custom-fields-by-id", + "type": "schemas" + }, + { + "_id": "reserved_field_definitions_response", + "type": "schemas" + }, + { + "_id": "custom_field_definitions_response", + "type": "schemas" + }, + { + "_id": "POST_mc-field_definitions", + "type": "endpoints" + }, + { + "_id": "GET_mc-field_definitions", + "type": "endpoints" + }, + { + "_id": "PATCH_mc-field_definitions-custom_field_id", + "type": "endpoints" + }, + { + "_id": "DELETE_mc-field_definitions-custom_field_id", + "type": "endpoints" + } + ], + "name": "Custom Fields", + "description": "Custom Fields allow you to add extra information about your contacts to your contact database. With custom fields, you can create custom segments from your individual contacts or from your contact database that will dynamically update your content with the values for the individual contact receiving the email. Your custom fields are completely customizable to the use cases and user information that you need.\n\nYou can also manage your Custom Fields using the [Custom Fields UI in the Marketing Campaigns App](https://mc.sendgrid.com/custom-fields). For more about creating Custom Fields, including a list of Reserved Fields, see our [Custom Fields documentation](https://sendgrid.com/docs/ui/managing-contacts/custom-fields/)." + }, + { + "divider": false, + "items": [ + { + "_id": "xJZx99h8rizghwRct", + "type": "traits" + }, + { + "_id": "segment_write", + "type": "schemas" + }, + { + "_id": "contact_response", + "type": "schemas" + }, + { + "_id": "segment_summary", + "type": "schemas" + }, + { + "_id": "full-segment", + "type": "schemas" + }, + { + "_id": "segment_query_json", + "type": "schemas" + }, + { + "_id": "POST_marketing-segments", + "type": "endpoints" + }, + { + "_id": "GET_marketing-segments-segmentid", + "type": "endpoints" + }, + { + "_id": "GET_marketing-segments", + "type": "endpoints" + }, + { + "_id": "PATCH_marketing-segments-segmentid", + "type": "endpoints" + }, + { + "_id": "DELETE_marketing-segments-segmentid", + "type": "endpoints" + }, + { + "_id": "POST_marketing-segments-delete", + "type": "endpoints" + } + ], + "name": "Segmenting Contacts", + "description": "Segments are similar to contact lists, except they update dynamically over time as information stored about your contacts or the criteria used to define your segments changes. When you segment your audience, you are able to create personalized Automation emails and Single Sends that directly address the wants and needs of your particular audience.\n\nThe Marketing Campaigns Segments API allows you to create, edit, and delete segments as well as retrieve a list of segments or an individual segment by ID.\n\n> Note that Twilio SendGrid checks for newly added or modified contacts who meet a segment's criteria on an hourly schedule. Only existing contacts who meet a segment's criteria will be included in the segment searches within 15 minutes.\n>\n> Segments built using engagement data such as \"was sent\" or \"clicked\" will take approximately 30 minutes to begin populating.\n>\n> Segment samples and counts are refreshed approximately once per hour; they do not update immediately. If no contacts are added to or removed from a segment since the last refresh, the sample and UI count displayed will be refreshed at increasing time intervals with a maximum sample and count refresh delay of 24 hours.\n\nFor more information on creating segments with the Twilio SendGrid Marketing Campaigns UI see [\"Segmenting your Contacts.\"](https://sendgrid.com/docs/ui/managing-contacts/segmenting-your-contacts/)\n\nFor help with Segmentation Query Language, see our [Segmentation Query Language reference](https://sendgrid.com/docs/for-developers/sending-email/segmentation-query-language/)" + }, + { + "divider": false, + "items": [ + { + "_id": "vve7kMhgurSwPWi6S", + "type": "schemas" + }, + { + "_id": "FTA2YcjxEPyAFfYe8", + "type": "schemas" + }, + { + "_id": "singlesend_request", + "type": "schemas" + }, + { + "_id": "singlesend_response_short", + "type": "schemas" + }, + { + "_id": "singlesend_response", + "type": "schemas" + }, + { + "_id": "singlesend_search", + "type": "schemas" + }, + { + "_id": "singlesend_schedule", + "type": "schemas" + }, + { + "_id": "singlesend_warning", + "type": "schemas" + }, + { + "_id": "abtest_summary", + "type": "schemas" + }, + { + "_id": "POST_marketing-singlesends", + "type": "endpoints" + }, + { + "_id": "POST_marketing-singlesends-id", + "type": "endpoints" + }, + { + "_id": "POST_marketing-singlesends-search", + "type": "endpoints" + }, + { + "_id": "PATCH_marketing-singlesends-id", + "type": "endpoints" + }, + { + "_id": "PUT_marketing-singlesends-id-schedule", + "type": "endpoints" + }, + { + "_id": "GET_marketing-singlesends", + "type": "endpoints" + }, + { + "_id": "GET_marketing-singlesends-id", + "type": "endpoints" + }, + { + "_id": "GET_marketing-singlesends-categories", + "type": "endpoints" + }, + { + "_id": "DELETE_marketing-singlesends-id", + "type": "endpoints" + }, + { + "_id": "DELETE_marketing-singlesends", + "type": "endpoints" + }, + { + "_id": "DELETE_marketing-singlesends-id-schedule", + "type": "endpoints" + } + ], + "name": "Single Sends", + "description": "A Single Send is a one-time nonautomated email message delivered to a list or segment of your audience. A Single Send may be sent immediately or scheduled for future delivery.\n\nSingle Sends can serve many use cases, including promotional offers, engagement campaigns, newsletters, announcements, legal notices, or policy updates.\n\nThe Single Sends API allows you to create, retrieve, update, delete, schedule, and deliver your Single Sends. There are also endpoints for searching and statistics to help you maintain and alter your Single Sends as you learn more and further develop your campaigns.\n\nThe Single Sends API changed on **May 6, 2020**. Please check the SendGrid Knowledge Center for updates and instructions here: [https://sendgrid.com/docs/for-developers/sending-email/single-sends-2020-update/](https://sendgrid.com/docs/for-developers/sending-email/single-sends-2020-update/)" + }, + { + "divider": false, + "items": [ + { + "_id": "POST_marketing-test-sendemail", + "type": "endpoints" + } + ], + "name": "Send Test Email" + }, + { + "divider": false, + "items": [ + { + "_id": "automationQueryParams", + "type": "traits" + }, + { + "_id": "singlesendQueryParams", + "type": "traits" + }, + { + "_id": "singlesendQueryParams2", + "type": "traits" + }, + { + "_id": "errorResponse", + "type": "traits" + }, + { + "_id": "baseParams", + "type": "traits" + }, + { + "_id": "pagination", + "type": "traits" + }, + { + "_id": "errors", + "type": "schemas" + }, + { + "_id": "metadata", + "type": "schemas" + }, + { + "_id": "metrics", + "type": "schemas" + }, + { + "_id": "singlesends-response", + "type": "schemas" + }, + { + "_id": "automations-response", + "type": "schemas" + }, + { + "_id": "automations-link-stats-response", + "type": "schemas" + }, + { + "_id": "singlesends-link-stats-response", + "type": "schemas" + }, + { + "_id": "link-tracking-metadata", + "type": "schemas" + }, + { + "_id": "getall-automation-stats", + "type": "endpoints" + }, + { + "_id": "get-automation-stat", + "type": "endpoints" + }, + { + "_id": "getall-singlesend-stats", + "type": "endpoints" + }, + { + "_id": "get-singlesend-stat", + "type": "endpoints" + }, + { + "_id": "get-automation-link-stat", + "type": "endpoints" + }, + { + "_id": "get-singlesend-link-stat", + "type": "endpoints" + }, + { + "_id": "get-singlesend-stats-export", + "type": "endpoints" + }, + { + "_id": "get-automations-stats-export", + "type": "endpoints" + } + ], + "name": "Marketing Campaigns Stats", + "description": "The Marketing Campaigns Stats endpoints allow you to retrieve stats for both Automations and Single Sends.\n\n**Note:** These endpoints provide stats for Marketing Campaigns only. For stats related to event tracking, please see the **Stats** section under **Event Tracking** below." + }, + { + "divider": true, + "items": [], + "name": "Legacy Marketing Campaigns" + }, + { + "name": "Sender Identities API", + "items": [ + { + "_id": "senderID", + "type": "schemas" + }, + { + "_id": "sender-id-request", + "type": "schemas" + }, + { + "_id": "POST_senders", + "type": "endpoints" + }, + { + "_id": "GET_v3-senders", + "type": "endpoints" + }, + { + "_id": "GET_v3-senders-sender_id", + "type": "endpoints" + }, + { + "_id": "PATCH_v3-senders-sender_id", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "POST_v3-senders-sender_id-resend_verification" + }, + { + "_id": "DELETE_v3-senders-sender_id", + "type": "endpoints" + } + ], + "description": "A [Sender Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) is the email address from which an email is sent. Sender Identities must be verified before use.\n\nIf your domain has been authenticated, it will auto verify on creation. Otherwise, a verification email will be sent to the `from.email`.", + "divider": false + }, + { + "items": [ + { + "type": "schemas", + "_id": "contactdb_list" + }, + { + "_id": "POST_contactdb-lists", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-lists", + "type": "endpoints" + }, + { + "_id": "DELETE_contactdb-lists", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-lists-listid", + "type": "endpoints" + }, + { + "_id": "PATCH_contactdb-lists-listid", + "type": "endpoints" + }, + { + "_id": "DELETE_contactdb-lists-listid", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-lists-listid-recipients", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "POST_contactdb-lists-listid-recipients-recipientid" + }, + { + "_id": "DELETE_contactdb-lists-listid-recipients-recipientid", + "type": "endpoints" + }, + { + "_id": "POST_contactdb-lists-listid-recipients", + "type": "endpoints" + } + ], + "name": "Contacts API - Lists", + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false + }, + { + "items": [ + { + "type": "schemas", + "_id": "contactdb_recipient_count" + }, + { + "_id": "contactdb_recipient", + "type": "schemas" + }, + { + "_id": "contactdb_recipient_response", + "type": "schemas" + }, + { + "_id": "contacts", + "type": "schemas" + }, + { + "_id": "POST_contactdb-recipients", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-status", + "type": "endpoints" + }, + { + "_id": "PATCH_contactdb-recipients", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "DELETE_contactdb-recipients" + }, + { + "_id": "GET_contactdb-recipients", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-recipients-recipientid", + "type": "endpoints" + }, + { + "_id": "DELETE_contactdb-recipients-recipientid", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-recipients-recipientid-lists", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-recipients-billablecount", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-recipients-count", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-recipients-search", + "type": "endpoints" + }, + { + "_id": "POST_contactdb-recipients-search", + "type": "endpoints" + } + ], + "name": "Contacts API - Recipients", + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false + }, + { + "items": [ + { + "_id": "contactdb_custom_field_with_id", + "type": "schemas" + }, + { + "_id": "contactdb_custom_field_with_id_value", + "type": "schemas" + }, + { + "type": "schemas", + "_id": "contactdb_custom_field" + }, + { + "_id": "POST_contactdb-customfields", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-customfields", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-customfields-customfieldid", + "type": "endpoints" + }, + { + "_id": "DELETE_contactdb-customfields-customfieldid", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-reservedfields", + "type": "endpoints" + } + ], + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false, + "name": "Contacts API - Custom Fields" + }, + { + "items": [ + { + "_id": "contactdb_segments", + "type": "schemas" + }, + { + "_id": "contactdb_segments_with_id", + "type": "schemas" + }, + { + "_id": "contactdb_segments_conditions", + "type": "schemas" + }, + { + "_id": "POST_contactdb-segments", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-segments", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-segments-segmentid", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "PATCH_contactdb-segments-segmentid" + }, + { + "_id": "DELETE_contactdb-segments-segmentid", + "type": "endpoints" + }, + { + "_id": "GET_contactdb-segments-segmentid-recipients", + "type": "endpoints" + } + ], + "name": "Contacts API - Segments", + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false + }, + { + "items": [ + { + "_id": "GET_categories", + "type": "endpoints" + }, + { + "_id": "GET_categories-stats-sums", + "type": "endpoints" + }, + { + "_id": "GET_categories-stats", + "type": "endpoints" + }, + { + "_id": "category_stats", + "type": "schemas" + } + ], + "name": "Categories", + "description": "Categories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories.\n\nYou can retrieve statistics based on your categories, but note that category statistics are only available for the previous thirteen months.", + "divider": false + }, + { + "name": "Campaigns API", + "description": "Allows you to create, manage, send, and schedule campaigns.", + "divider": false, + "items": [ + { + "_id": "campaign_request", + "type": "schemas" + }, + { + "type": "schemas", + "_id": "campaign_response" + }, + { + "_id": "POST_campaigns", + "type": "endpoints" + }, + { + "_id": "GET_campaigns", + "type": "endpoints" + }, + { + "_id": "GET_campaigns-campaignid", + "type": "endpoints" + }, + { + "_id": "DELETE_campaigns-campaignid", + "type": "endpoints" + }, + { + "_id": "PATCH_campaigns-campaignid", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "POST_campaigns-campaignid-schedules-now" + }, + { + "_id": "POST_campaigns-campaignid-schedules", + "type": "endpoints" + }, + { + "_id": "PATCH_campaigns-campaignid-schedules", + "type": "endpoints" + }, + { + "_id": "GET_campaigns-campaignid-schedules", + "type": "endpoints" + }, + { + "_id": "DELETE_campaigns-campaignid-schedules", + "type": "endpoints" + }, + { + "_id": "POST_campaigns-campaignid-schedules-test", + "type": "endpoints" + } + ] + }, + { + "divider": true, + "items": [], + "name": "Templates" + }, + { + "items": [ + { + "_id": "transactional_template", + "type": "schemas" + }, + { + "_id": "transactional-templates-template-lean", + "type": "schemas" + }, + { + "_id": "transactional-template-warning", + "type": "schemas" + }, + { + "_id": "POST_templates", + "type": "endpoints" + }, + { + "_id": "POST_templates-templateid", + "type": "endpoints" + }, + { + "_id": "GET_templates", + "type": "endpoints" + }, + { + "_id": "GET_templates-templateid", + "type": "endpoints" + }, + { + "_id": "PATCH_templates-templateid", + "type": "endpoints" + }, + { + "_id": "DELETE_templates-templateid", + "type": "endpoints" + } + ], + "name": "Transactional Templates", + "description": "An HTML template that can establish a consistent design for [transactional emails](https://sendgrid.com/use-cases/transactional-email/).\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 designs](https://sendgrid.com/docs/ui/sending-email/working-with-marketing-campaigns-email-designs/). For more information about transactional templates, please see our [Dynamic Transactional Templates documentation](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).", + "divider": false + }, + { + "items": [ + { + "_id": "transactional-templates-version-output-lean", + "type": "schemas" + }, + { + "_id": "transactional_template_version_create", + "type": "schemas" + }, + { + "_id": "transactional_template_version_output", + "type": "schemas" + }, + { + "_id": "POST_templates-templateid-versions", + "type": "endpoints" + }, + { + "_id": "POST_templates-templateid-versions-versionid-activate", + "type": "endpoints" + }, + { + "_id": "GET_templates-templateid-versions-versionid", + "type": "endpoints" + }, + { + "_id": "PATCH_templates-templateid-versions-versionid", + "type": "endpoints" + }, + { + "_id": "DELETE_templates-templateid-versions-versionid", + "type": "endpoints" + } + ], + "name": "Transactional Templates Versions", + "description": "Represents the code for a particular transactional template. Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [Transactional Templates documentation](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/). You can also manage your Transactional Templates in the [Dynamic Templates section of the Twilio SendGrid App](https://mc.sendgrid.com/dynamic-templates).", + "divider": false + }, + { + "divider": true, + "items": [], + "name": "Event Tracking" + }, + { + "description": null, + "divider": false, + "items": [ + { + "_id": "webhooks-event-webhook-request", + "type": "schemas" + }, + { + "_id": "event-webhook-response", + "type": "schemas" + }, + { + "_id": "event-webhook-update-oauth-request", + "type": "schemas" + }, + { + "_id": "GET_user-webhooks-event-settings", + "type": "endpoints" + }, + { + "_id": "GET_user-webhooks-parse-settings", + "type": "endpoints" + }, + { + "_id": "GET_user-webhooks-parse-stats", + "type": "endpoints" + }, + { + "_id": "GET_user-webhooks-event-settings-signed", + "type": "endpoints" + }, + { + "_id": "POST_user-webhooks-event-test", + "type": "endpoints" + }, + { + "_id": "PATCH_user-webhooks-event-settings", + "type": "endpoints" + }, + { + "_id": "PATCH_user-webhooks-event-settings-signed", + "type": "endpoints" + } + ], + "name": "Webhooks" + }, + { + "divider": false, + "items": [ + { + "_id": "GET-messages", + "type": "endpoints" + }, + { + "_id": "GET-v3-messages-msg_id", + "type": "endpoints" + }, + { + "_id": "POST_v3-messages-download", + "type": "endpoints" + }, + { + "_id": "GET_v3-messages-download-download_uuid", + "type": "endpoints" + }, + { + "_id": "email-activity-response-common-fields", + "type": "schemas" + } + ], + "name": "Email Activity", + "description": "**You must purchase [additional email activity history](https://app.sendgrid.com/settings/billing/addons/email_activity) to gain access to the Email Activity Feed API.**\n\nThe Email Activity API allows you to query all of your stored messages, query individual messages, and download a CSV with data about the stored messages.\n\nOnce retrieved, you can inspect the data associated with your messages to better understand your mail send. For example, you may retrieve all bounced messages or all messages with the same subject line and search for commonalities among them.\n\nSee \"[Getting Started with the Email Activity Feed API](https://sendgrid.com/docs/for-developers/sending-email/getting-started-email-activity-api/)\" for help building queries and working with the API.\n\nYou can also work with email activity in the **Activity** section of the [Twilio SendGrid App](https://app.sendgrid.com/email_activity)." + }, + { + "items": [ + { + "_id": "subscription_tracking_settings", + "type": "schemas" + }, + { + "_id": "click-tracking", + "type": "schemas" + }, + { + "_id": "google_analytics_settings", + "type": "schemas" + }, + { + "_id": "GET_trackingsettings", + "type": "endpoints" + }, + { + "_id": "GET_trackingsettings-click", + "type": "endpoints" + }, + { + "_id": "PATCH_trackingsettings-click", + "type": "endpoints" + }, + { + "_id": "GET_trackingsettings-googleanalytics", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "PATCH_trackingsettings-googleanalytics" + }, + { + "_id": "GET_trackingsettings-open", + "type": "endpoints" + }, + { + "_id": "PATCH_trackingsettings-open", + "type": "endpoints" + }, + { + "_id": "GET_trackingsettings-subscription", + "type": "endpoints" + }, + { + "_id": "PATCH_trackingsettings-subscription", + "type": "endpoints" + } + ], + "name": "Settings - Tracking", + "description": "You can track many of your recipients' interactions with your emails, including:\n\n- Opening emails\n- Clicking links\n- Subscribing to (or unsubscribing from) your emails\n\nFor more information about tracking, please see our [Tracking Settings documentation](https://sendgrid.com/docs/ui/account-and-settings/tracking/).", + "divider": false + }, + { + "divider": false, + "items": [ + { + "_id": "Ag8mEYHMm5BNuLh4B", + "type": "schemas" + }, + { + "_id": "statsAdvancedStatsBaseQueryStrings", + "type": "traits" + }, + { + "_id": "statsAdvancedQueryStringsLimitOffset", + "type": "traits" + }, + { + "_id": "advanced_stats_mailbox_provider", + "type": "schemas" + }, + { + "_id": "stats-advanced-global-stats", + "type": "schemas" + }, + { + "_id": "GET_stats", + "type": "endpoints" + }, + { + "_id": "GET_geo-stats", + "type": "endpoints" + }, + { + "_id": "GET_devices-stats", + "type": "endpoints" + }, + { + "_id": "GET_clients-stats", + "type": "endpoints" + }, + { + "_id": "GET_clients-clienttype-stats", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "GET_mailboxproviders-stats" + }, + { + "_id": "GET_browsers-stats", + "type": "endpoints" + }, + { + "_id": "stats-advanced-stats-base-schema", + "type": "schemas" + }, + { + "type": "schemas", + "_id": "advanced_stats_clicks" + }, + { + "_id": "advanced_stats_opens", + "type": "schemas" + }, + { + "_id": "advanced_stats_clicks_opens", + "type": "schemas" + } + ], + "name": "Stats", + "description": "Tracking your emails is an important part of being a good sender and learning about how your users interact with your email. This includes everything from basics of clicks and opens to looking at which browsers and mailbox providers your customers use.\n\nWe have broken up statistics in specific ways so that you can get at-a-glance data, as well as allowing you to get into the details of how your email is being used.\n\n> Category statistics are available for the previous thirteen months only." + }, + { + "divider": true, + "items": [], + "name": "Suppression Management" + }, + { + "description": "An email is considered [bounced](https://sendgrid.com/docs/glossary/bounces/) when the message is undeliverable and then returned to the server that sent it. Bounced emails can be either permanent or temporary failures to deliver the message.\n\nFor more information, see our [Bounces documentation](https://sendgrid.com/docs/ui/sending-email/bounces/).\n\nYou can also manage bounced emails from the [Suppression settings menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", + "divider": false, + "items": [ + { + "_id": "GET_suppression-bounces", + "type": "endpoints" + }, + { + "_id": "GET_suppression-bounces-email", + "type": "endpoints" + }, + { + "_id": "DELETE_suppression-bounces", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "DELETE_suppression-bounces-email" + }, + { + "type": "schemas", + "_id": "bounce_response" + } + ], + "name": "Bounces API" + }, + { + "items": [ + { + "_id": "GET_suppression-blocks", + "type": "endpoints" + }, + { + "_id": "GET_suppression-blocks-email", + "type": "endpoints" + }, + { + "_id": "DELETE_suppression-blocks", + "type": "endpoints" + }, + { + "_id": "DELETE_suppression-blocks-email", + "type": "endpoints" + }, + { + "_id": "blocks-response", + "type": "schemas" + } + ], + "name": "Blocks API", + "description": "[Blocks](https://sendgrid.com/docs/glossary/blocks/) happen when your email is rejected because of an issue with the message itself rather than an issue with the recipient's address.\n\nThere are several causes for blocked emails. For example, your mail server IP address may be blocked by an ISP, or the receiving server may flag the message content using a filter. Twilio SendGrid will not suppress future messages to blocked addresses by default. \n\nFor more information, please see our [Blocks documentation](https://sendgrid.com/docs/ui/sending-email/blocks/).\n\nYou can also see your Blocks in the [Suppressions settings menu of the Twilio SendGrid App](https://app.sendgrid.com/suppressions/blocks).", + "divider": false + }, + { + "items": [ + { + "_id": "GET_suppression-spamreports", + "type": "endpoints" + }, + { + "_id": "GET_suppression-spamreports-email", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "DELETE_suppression-spamreports" + }, + { + "_id": "DELETE_suppression-spamreports-email", + "type": "endpoints" + }, + { + "_id": "spam-reports-response", + "type": "schemas" + } + ], + "name": "Spam Reports API", + "description": "Spam Reports are triggered when a recipient marks one of your emails as spam. Spam reports can only be gathered from Internet Service Providers (ISPs) that provide a feedback loop.\n\nIt is important that addresses that have marked your messages as spam be permanently removed from your send list, even if the recipients have previously opted into receiving your messages. Continuing to send to customers who have reported your email as spam can severely affect your deliverability rating.\n\nYou can also access your Spam Reports from the [Suppressions settings menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/spam_reports).\n\nFor more information, please see our [Spam Reports documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/spam-reports/).", + "divider": false + }, + { + "items": [ + { + "_id": "POST_asm-suppressions-global", + "type": "endpoints" + }, + { + "_id": "GET_suppression-unsubscribes", + "type": "endpoints" + }, + { + "_id": "GET_asm-suppressions-global-email", + "type": "endpoints" + }, + { + "_id": "DELETE_asm-suppressions-global-email", + "type": "endpoints" + }, + { + "_id": "suppressions-request", + "type": "schemas" + } + ], + "name": "Suppressions - Global Suppressions", + "description": "A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [Global Unsubscribes documentation](https://sendgrid.com/docs/ui/sending-email/global-unsubscribes/).", + "divider": false + }, + { + "divider": false, + "items": [ + { + "_id": "POST_asm-groups", + "type": "endpoints" + }, + { + "_id": "GET_asm-groups", + "type": "endpoints" + }, + { + "_id": "GET_asm-groups-groupid", + "type": "endpoints" + }, + { + "_id": "PATCH_asm-groups-groupid", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "DELETE_asm-groups-groupid" + }, + { + "_id": "suppression-group-request-base", + "type": "schemas" + }, + { + "_id": "suppression_group", + "type": "schemas" + } + ], + "name": "Suppressions - Unsubscribe Groups", + "description": "Suppression groups, or unsubscribe groups, are specific types or categories of emails from which you would like your recipients to be able to unsubscribe. For example: Daily Newsletters, Invoices, and System Alerts are all potential suppression groups. Visit the main documentation to [learn more about suppression/unsubscribe groups](https://sendgrid.com/docs/ui/sending-email/unsubscribe-groups/)\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach Twilio SendGrid account can create up to 25 different suppression groups." + }, + { + "name": "Suppressions - Suppressions", + "items": [ + { + "_id": "POST_asm-groups-groupid-suppressions", + "type": "endpoints" + }, + { + "type": "endpoints", + "_id": "POST_asm-groups-groupid-suppressions-search" + }, + { + "_id": "GET_asm-groups-groupid-suppressions", + "type": "endpoints" + }, + { + "_id": "GET_asm-suppressions", + "type": "endpoints" + }, + { + "_id": "GET_asm-suppressions-email", + "type": "endpoints" + }, + { + "_id": "DELETE_asm-groups-groupid-suppressions-email", + "type": "endpoints" + } + ], + "description": "Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/ui/sending-email/unsubscribe-groups/). 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.", + "divider": false + }, + { + "items": [ + { + "_id": "GET_suppression-invalidemails", + "type": "endpoints" + }, + { + "_id": "GET_suppression-invalidemails-email", + "type": "endpoints" + }, + { + "_id": "DELETE_suppression-invalidemails", + "type": "endpoints" + }, + { + "_id": "DELETE_suppression-invalidemails-email", + "type": "endpoints" + }, + { + "_id": "invalid-email", + "type": "schemas" + } + ], + "name": "Invalid Emails API", + "description": "\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server.\n\nExamples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [Invalid Email documentation](https://sendgrid.com/docs/ui/sending-email/invalid-emails/).", + "divider": false + }, + { + "divider": true, + "items": [], + "name": "Inbound Parse" + }, + { + "items": [ + { + "_id": "parse-setting", + "type": "schemas" + }, + { + "_id": "POST_user-webhooks-parse-settings", + "type": "endpoints" + }, + { + "_id": "GET_user-webhooks-parse-settings", + "type": "endpoints" + }, + { + "_id": "GET_user-webhooks-parse-settings-hostname", + "type": "endpoints" + }, + { + "_id": "PATCH_user-webhooks-parse-settings-hostname", + "type": "endpoints" + }, + { + "_id": "DELETE_user-webhooks-parse-settings-hostname", + "type": "endpoints" + } + ], + "name": "Settings - Inbound Parse", + "divider": false, + "description": "Twilio SendGrid’s Inbound Parse Webhook allows you to receive emails as multipart/form-data at a URL of your choosing. SendGrid will grab the content, attachments, and the headers from any email it receives for your specified hostname.\n\nSee \"[Setting up the Inbound Parse Webhook](https://sendgrid.com/docs/for-developers/parsing-email/setting-up-the-inbound-parse-webhook/)\" for help configuring the Webhook. You can also manage the Inbound Parse Webhook in the [Twilio SendGrid App](https://app.sendgrid.com/settings/parse).\n\nTo begin processing email using SendGrid's Inbound Parse Webhook, you will have to setup MX Records, choose the hostname (or receiving domain) that will be receiving the emails you want to parse, and define the URL where you want to POST your parsed emails. If you do not have access to your domain's DNS records, you must work with someone in your organization who does." + }, + { + "divider": false, + "name": "Global: Models", + "items": [ + { + "_id": "global_error_response_schema", + "type": "schemas" + }, + { + "_id": "global:id", + "type": "schemas" + }, + { + "_id": "global:empty_request", + "type": "schemas" + }, + { + "_id": "selfmetadata", + "type": "schemas" + }, + { + "_id": "error", + "type": "schemas" + }, + { + "_id": "link", + "type": "schemas" + }, + { + "_id": "metadata", + "type": "schemas" + }, + { + "_id": "webhook", + "type": "schemas" + } + ], + "description": "Elements that can be shared among more than one endpoint definition." + }, + { + "name": "Global: Traits", + "items": [ + { + "_id": "onBehalfOfSubuser", + "type": "traits" + }, + { + "_id": "globalErrors", + "type": "traits" + }, + { + "_id": "makoErrorResponse", + "type": "traits" + } + ], + "description": "Elements that can be shared among more than one endpoint definition.", + "divider": false + }, + { + "items": [ + { + "_id": "credentials", + "type": "schemas" + } + ], + "name": "Credentials", + "description": null, + "divider": false + } + ] + } + }, + "functions": {}, + "textSections": { + "api-responses": { + "id": "api-responses", + "name": "Responses", + "content": "## Content-Type Header\n\nAll responses are returned in JSON format. We specify this by sending the `Content-Type` header.\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\n```\n\n```json\nHTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n \"foo\": \"bar\"\n}\n```\n\n## Status Codes\n\nBelow is a table containing descriptions of the various status codes we currently support against various resources.\n\n| **Status Code** | **Description** |\n|---|---|\n| 200 | No error |\n| 201 | Successfully created |\n| 204 | Successfully deleted |\n| 400 | Bad request|\n| 401 | Requires authentication |\n| 403 | From address doesn't match Verified Sender Identity. To learn how to resolve this error, see our [Sender Identity requirements]({{root_url}}for-developers/sending-email/sender-identity/). |\n| 406 | Missing Accept header. For example: `Accept: application/json` |\n| 429 | Too many requests/Rate limit exceeded |\n| 500 | Internal server error |\n\n\n## Pagination\n\nWhen a request is made with a pagination query, the following data is included in the header to allow for easy traversal of previous, current, first, and last page of the data set.\n\n```bash\nGET https://api.sendgrid.com/v3/resource?limit=5&offset=0 HTTP/1.1\n```\n\n```json\nHTTP/1.1 200 OK\nContent-Type: application/json\n\nLink: ; rel=\"next\"; title=\"2\",\n ; rel=\"prev\"; title=\"1\",\n ; rel=\"last\"; title=\"3\",\n ; rel=\"first\"; title=\"1\"\n\n```", + "public": true + }, + "mail-send-limitations": { + "id": "mail-send-limitations", + "name": "Limitations", + "content": "There are several rate limitations and restrictions that you should be aware of when using the v3 Mail Send endpoint.\n\n* The total size of your email, including attachments, must be less than 30MB.\n* The total number of recipients must no more than 1000. This includes all recipients defined within the `to`, `cc`, and `bcc` parameters, across each object that you include in the `personalizations` array.\n* The total length of custom arguments must be less than 10000 bytes.\n* Unicode encoding is not supported for the `from` field.\n* The `to.name`, `cc.name`, and `bcc.name` personalizations cannot include either the `;` or `,` characters.\n\nFor more specific, parameter level requirements and limitations, please refer to the [v3/mail/send documentation](https://sendgrid.api-docs.io/v3.0/mail-send/v3-mail-send).", + "public": true + }, + "mail-send-validation": { + "id": "mail-send-validation", + "name": "Validation", + "content": "Whenever you make a request to the v3 Mail Send endpoint, your JSON payload is validated before your email is sent. If there are any errors, SendGrid will attempt to identify and return as many issues as possible for each request. For more information, please read our [error documentation](https://sendgrid.api-docs.io/v3.0/mail-send/mail-send-errors).", + "public": true + }, + "api-errors": { + "id": "api-errors", + "name": "Errors", + "content": "Sometimes your API call will generate an error. Here you will find additional information about what to expect if you don’t format your request properly, or we fail to properly process your request.\n\n## Response Codes\n\n| **Status Code** | **Description** |\n|---|---|\n| 400 | Bad request|\n| 401 | Requires authentication |\n| 406 | Missing Accept header. For example: `Accept: application/json` |\n| 429 | Too many requests/Rate limit exceeded |\n| 500 | Internal server error |\n\n## Failed Requests\n\nThe general format guidelines are displayed when the accompanying status code is returned.\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\n```\n\n```json\nHTTP/1.1 400 BAD REQUEST\nContent-Type: application/json\n\n{\n \"errors\": [\n {\"field\": \"identifier1\", \"message\": \"error message explained\"},\n {\"field\": \"identifier2\", \"message\": \"error message explained\"},\n {\"field\": \"identifier3\", \"message\": \"error message explained\"},\n ]\n}\n```", + "public": true + }, + "api-authentication": { + "id": "api-authentication", + "name": "Authentication", + "content": "## Authorization Header\n\nTo authenticate, add an `Authorization` header to your API request that contains an [API Key](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/index.html).\n\n## API Keys\n\nSendGrid’s Web API v3 supports the use of API Keys. API Keys allow you to use another method of authentication separate from your account username and password. API Keys add an additional layer of security for your account and can be assigned [specific permissions](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) to limit which areas of your account they may be used to access. [API Keys can be generated in your account](https://app.sendgrid.com/settings/api_keys). To use keys, you must set a plain text header named “Authorization” with the contents of the header being “Bearer XXX” where XXX is your API Secret Key.\n\n### Example Header\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\nAuthorization: Bearer Your.API.Key-HERE\n```\n\n```bash\ncurl -X \"GET\" \"https://api.sendgrid.com/v3/templates\" -H \"Authorization: Bearer Your.API.Key-HERE\" -H \"Content-Type: application/json\"\n```", + "public": true + }, + "api-rate-limits": { + "id": "api-rate-limits", + "name": "Rate Limits", + "content": "## Rate Limit Response Header\n\nAll calls within the Web API are allotted a specific number of requests per refresh period.\n\nEach Web API request returns the following header information regarding rate limits and number of requests left.\n\nDepending on the endpoint you are trying to reach, it will have a specific number of allowed requests per refresh period. Once this threshold has been reached, we will return a status code `429` response.\n\n### Example\n\n```bash\nGET https://api.sendgrid.com/v3/resource HTTP/1.1\n```\n\n```json\nHTTP/1.1 200 OK\nContent-Type: application/json\nX-RateLimit-Limit: 500\nX-RateLimit-Remaining: 499\nX-RateLimit-Reset: 1392815263\n\n{\n \"foo\": \"bar\"\n}\n```\n\n## When You Reach a Rate Limit\n\nYou will no longer be able to make request against that endpoint for the duration of that refresh period.\n\n### Example\n\n```bash\nGET https://api.sendgrid.com/v3/resource/ HTTP/1.1\n```\n\n```json\nHTTP/1.1 429 TOO MANY REQUESTS\nContent-Type: application/json\nX-RateLimit-Limit: 150\nX-RateLimit-Remaining: 0\nX-RateLimit-Reset: 1392815263\n\n{\n \"errors\": [\n {\n \"field\": null,\n \"message\": \"too many requests\"\n },\n ]\n}\n```", + "public": true + }, + "api-requests": { + "id": "api-requests", + "name": "Requests", + "content": "## Making a Request\n\n### Host\n\nThe host for Web API v3 requests is always `https://sendgrid.com/v3/`\n\n**All requests must be made over HTTPS. The API does not support HTTP.**\n\n### Authorization Header\n\nYou must provide an authorization header as described in [Authentication]().\n\n### HTTP Verbs\n\n| **Verb** | **Description** |\n| --- | --- |\n| GET | Retrieve a resource or group of resources |\n| POST| Create a new resource |\n| PUT | Update an existing resource |\n| DELETE | Delete an existing resource |\n| OPTIONS | View allowed verbs against a specific resource |\n\n### Accept Header\n\nThe API provides JSON responses. It doesn't currently require the [accept header](http://www.soapui.org/Best-Practices/understanding-rest-headers-and-parameters.html), but might in the future. If not set, the API will use `application/json`.\n\n```bash\nGET https://api.sendgrid.com/v3/endpoint HTTP/1.1\nAccept: application/json\n```\n\n### Arrays of Data\n\nWhen you send an array of data in a `GET` request, you will include the parameter multiple times on the URL. The parameter name does not require brackets.\n\n#### Example Array in a GET request\\\n\n```bash\nGET https://api.sendgrid.com/v3/endpoint?parameter=data1¶meter=data2 HTTP/1.1\n```\n\n## Formatting Your Request\n\n### Request Body\n\nWhen submitting data to a resource via `POST` or `PUT`, you must submit your payload in JSON.\n\n```bash\nPOST https://api.sendgrid.com/v3/templates/ HTTP/1.1\nContent-Type: application/json\n```\n\n```json\n{\n \"name\": \"new template name\"\n}\n```\n\n### Pagination\n\nSome `GET` resources allow for retrieval of information in batches. We will provide the query args in the resource documentation when available to consume.\n\nWhen requesting multiple items, we will default the request limit to 500 items. You can specify a different limit but cannot exceed the default limit.\n\nResources documented will display a bolded list of available paginated parameters if available.\n\nBelow is a basic pagination example. In the resource documentation, we will only provide the bolded list of available parameters.\n\n**A [Link Header](http://tools.ietf.org/html/rfc5988) is provided in the response for batched information.**\n\n```bash\nGET https://api.sendgrid.com/v3/resource?limit=300&offset=10 HTTP/1.1\n```\n\n| **Parameter** | **Description** |\n|---|---|\n| limit | The number of records to return |\n| offset | The number of records to skip |\n\n### Search & Paramters\n\nSome resources allow for you to search by a specific field. Other resources require you to append a parameter to the URI.\n\nIn this example, we will display a paginated URI example, searching for resources where the email contains `foo`.\n\n```bash\nGET https://api.sendgrid.com/v3/resource?email=foo&bar=baz HTTP/1.1\n```\n\n## Successful Requests\n\nBelow is a general overview of what resource objects return with successful Web API requests.\n\n| **Verb** | **Resource object returned** |\n|---|---|\n| GET | Returns a single resource object or array of resource objects |\n| PATCH | Returns the updated resource object |\n| PUT | Returns the updated resource object |\n| DELETE | No content is returned |\n| POST | Returns the newly created resource object |", + "public": true + }, + "mail-send-errors": { + "id": "mail-send-errors", + "name": "Errors", + "content": "\n\n\n

Personalizations Errors

\n\n\n\n\n

personalizations

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n\n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n \n
Error CodeError MessageDetails
400
The personalization block is limited to 1000 personalizations per API request. You have provided X personalizations. Please consider splitting this into multiple requests and resending your request.
The v3 Mail Send endpoint is only capable of processing 1000 individual personalizations objects per request. If you need to send your email to more than 1000 different recipients, we recommend that you simply make more than one call. For more information about the personalizations array, and how you can use it to define who you would like you send your email to, and how you would like your email to be processed, please visit our Personalizations documentation.
You must have at least one personalization.
Every email you send must have at least one recipient email address included. Recipients are defined in the personalizations array. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
There is a limit of 1000 total recipients (to + cc + bcc) per request.
The combined, total number of email recipients may never exceed 1000. This includes recipients defined within the to, cc, and bcc parameters. For more information on how you may specify your recipients, please visit our Personalizations documentation.
Each \"to\" object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every recipient that you define within a personalizations.to parameter, you must include one valid email address. You are not required to include a name.
Each unique email address in the personalizations array should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Personalizations documentation.
The to parameter is required for all personalization objects.
For every single object that you include within the personalizations array, you must include at least one to email object with a valid email address. For more information on how you may specify your recipients, please visit our Personalizations documentation.
\n\n\n\n\n

personalizations.bcc

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bcc array, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every blind carbon copy of your email, you must include one, valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
Each recipient object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
Every recipient that you define within the personalizations.cc array must be in the form of an email object including one, valid email address. You are not required to include a name.
Each unique email address in the personalization block should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Personalizations documentation.
\n\n\n\n\n

personalizations.cc

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The cc array, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every carbon copy of your email, you must include one valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
Each recipient object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
Every recipient that you define within the personalizations.cc array must be in the form of an email object including one, valid email address. You are not required to include a name.
Each unique email address in the personalization block should only be included once. You have included [email address] more than once.
To prevent the same email from being delivered to one recipient multiple times, SendGrid will confirm that you do not duplicate an email address in your request. For more information on how you may specify your recipients, please visit our Personalizations documentation.
\n\n\n\n\n

personalizations.custom_args

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
All values of custom arguments object must be strings
Custom argument values must always be strings. You cannot define arrays, integers, or booleans as custom argument values. Click here more information about how to use custom arguments.
custom_args cannot be empty.
If you include the custom_args parameter, you must include at least one value. If you do not want to use any custom arguments, simply omit the custom_arg param from your request. Click here more information about how to use custom arguments.
The combined size of both global and personalization custom arguments may not exceed 10,000 bytes per personalization.
personalizations[x].custom_args will be merged with message level custom_args, overriding any conflicting keys. The combined total size of the resulting custom arguments, after merging, for each personalization may not exceed 10,000 bytes. Click here more information about how to use custom arguments.
\n\n\n\n\n

personalizations.headers

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
All values of the headers object must be strings.
The object type of every header that you include must be a string. You cannot include headers that are integers, booleans, or arrays.
The headers cannot contain duplicate keys.
You may not include the same header more than once.
Header keys cannot contain non-ASCII characters or empty spaces.
When defining the headers that you would like to use, you must make sure that the string contains only ASCII characters.
Header cannot be one of the reserved keys.
Some header keys are reserved. You may not include any of the following reserved keys: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.
\n\n\n\n\n

personalizations.send_at

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The send_at parameter is expecting a Unix timestamp as an integer. We will send immediately if you include a send_at timestamp that is in the past.
send_at accepts a unix timestamp representing when you want your email to be sent from SendGrid. If you want the email to be sent at the time of your API request, simply omit the send_at parameter.
Scheduling more than 72 hours in advance is forbidden.
The send_at parameter allows you to schedule your email to be sent up to 72 hours in advance, but due to our constraints, we cannot schedule emails more than 72 hours in the future. For more information on scheduling parameters, please see our API Reference.
\n\n\n\n\n

personalizations.subject

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subject of your email must be a string at least one character in length.
You are required to include a subject for every email you send, and you may not include an empty subject. The minimum length of your subject is one character.
The subject is required. You can get around this requirement if you use a template with a subject defined.
Every email must have a subject. This can be accomplished 3 ways: you include a template that has a subject, you define a global subject, or every single personalizations object has a subject.
\n\n\n\n\n

personalizations.substitutions

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The substitution values must be an object of key/value pairs, where the values are all strings.
Substitutions must always follow the pattern \"substitution_tag\": \"value to substitute\". The value to substitute for the \"substitution_tag\" must always be a string.
You are limited to 10,000 substitutions.
You may not make more than 10,000 bytes worth of substitutions per request. Substitutions will apply to the content of your email, in addition to the subject and reply_to parameters
\n\n\n\n\n

personalizations.to

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The to array must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
Every email you send must have at least one, valid recipient email address included. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
\n\n\n\n\n

ASM Errors

\n\n\n\n\n

asm.group_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The ASM group ID must be an integer.
Suppression Groups, or unsubscribe groups, are a great way to record which emails your recipients want to receive. Including the asm.group_id in your request allows you to group your email with other, similar sends. However, these group IDs are always generated as integers, and so you must ensure that asm.group_id is defined as an integer. For more information please read our Unsubscribe Groups documentation.
The ASM group ID must be a valid Group ID on your account. You provided [YOUR ASM GROUP ID].
\n\n\n\n\n

asm.groups_to_display

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The ASM Group IDs to display must be an array of integers.
All ASM groups to display must be valid ASM groups IDs on your account. You provided {invalid IDs}.
There is a limit of 25 unsubscribe groups that can be displayed to a user at a time.\n
\n\n\n\n\n

Attachment Errors

\n\n\n\n\n

attachments.content

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The attachment content must be base64 encoded.
The attachment content must be a string at least one character in length.
\n\n\n\n\n

attachments.content_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The content ID of your attachment must be a string. You provided [YOUR CONTENT ID].
The content_id is a unique id that you specify for the attachment. This is used when the disposition is set to \"inline\" and the attachment is an image, allowing the file to be displayed within the body of your email. For example, <img src=\"cid:ii_139db99fdb5c3704\"></img>
The content ID of your attachment cannot contain CRLF characters.
When defining your content_id, you may not include the characters ;, ,, n, or r.
\n\n\n\n\n

attachments.disposition

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The disposition of your attachment can be either \"inline\" or \"attachment\". You provided [YOUR DISPOSITION].
The content-disposition of your attachment defines how you would like the attachment to be displayed. For example, \"inline\" results in the attached file being displayed automatically within the message while \"attachment\" results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file). attachments.disposition always defaults to \"attachment\". Can be either \"attachment\" or \"inline\".
\n\n\n\n\n

attachments.filename

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The filename of your attachment must be a string.
The filename of your attachment cannot contain CRLF characters.
When defining the filename of your attachment, you may not include the characters ;, ,, n, or r.
filename is required.
You must always include a filename for your attachment.
\n\n\n\n\n

attachments.type

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The attachment type must be a string and at least one character in length.
The type cannot contain ‘;’, or CRLF characters.
When defining the type of your attachment content, you may not include the characters ;, ,, n, or r.
\n\n\n\n\n

Batch ID Errors

\n\n\n\n\n

batch_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The batch_id must be a string.
Batch IDs are always generated as strings, so when you choose to include a batch ID in your send, you must make sure that batch_id is defined as a string. You must first generate a batch_id via the API; it will not be automatically generated for you. See the Create a Batch ID API reference to generate a batch_id. For more information about batch IDs, and how you can use them to group sends together, please visit our API Reference.
\n\n\n\n\n

Categories Errors

\n\n\n\n\n

categories

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
There is a limit of 10 categories for each email that is sent. You provided X categories.
For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
Categories must be an array of strings.
Every object that you include within the categories array must be a string. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
Each category must not be longer than 255 characters. [YOUR CATEGORY] exceeds this limit
he maximum length of a category is 255 characters. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
The categories must be a unique list, and you have included [YOUR CATEGORY] more than once.
You cannot include the same category more than once within the categories array. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
Categories can not contain non-ASCII characters.
Each category name must only be comprised of ASCII characters. For more information on how you can use categories to organize your email analytics, please visit our Categories documentation.
\n\n\n\n\n

Content Errors

\n\n\n\n\n

content

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The content param is required unless you are using a transactional template and have defined a template_ID.
You may not send an email without the content parameter unless you are using a transactional template. This is to prevent you from sending an empty email to your recipients.
There must be at least one defined content block. We typically suggest both text/plain and text/html blocks are included, but only one block is required.
You must specify at least one content type and value for every email you send. We recommend that you include both text/plain and text/html to ensure that all of your recipients are able to read your email, but you are only required to define one type of content.
\n\n\n\n\n

content.type

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
A content type is required, this tells email clients how to display the email.
You must always specify the MIME type of content you are including in your email, and if you are including the text/plain type, it must be specified first, followed by text/html, and then any other MIME types you would like to specify.
The content value must be a string at least one character in length.
You may not send an email with no content.
Your content type must be a string with length of at least one character.
The content of your email must always be contained within a string when you make your request.
Cannot contain ‘;’, or CRLF characters.
When defining the type of your content, you may not include the characters ;, ,, n, or r.
\n\n\n\n\n

content.value

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
A content value is required, this is the content of the email you are sending.
We do not allow you to send an empty email to your recipients. You must always include a value for your content.
The content value must be a string at least one character in length.
We do not allow you to send an empty email to your recipients. Even if you include the content.value parameter, it must include at least one character.
Following RFC 1341, section 7.2, if either text/html or text/plain are to be sent in your email: text/plain needs to be first, followed by text/html, followed by any other content.
The order in which you specify the MIME types of your content must always be text/plain first, if you choose to include it, followed by text/html, and then any other MIME types you wish to include.
\n\n\n\n\n

Encoding Errors

\n\n\n\n\n

Encoding

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
415
Invalid UTF8 in request
Your payload must be encoded in UTF-8. This includes any attachments.
\n\n\n\n\n

From Address Errors

\n\n\n\n\n

from

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The from object must at least have an email parameter with a valid email address and may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
While every from parameter must include a valid email address, you are not required to include a name.
The from object must be provided for every email send. It is an object that requires the email parameter, but may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
You are required to provide a from address whenever you send an email through SendGrid. This is used for authentication purposes and helps to build a positive sending reputation with your recipients' ISPs. You are not required to include a name within the from parameter.
\n\n\n\n\n

Headers Errors

\n\n\n\n\n

headers

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The header values must be strings.
The object type of every header that you include must be a string. You cannot include headers that are integers, booleans, or arrays.
The headers cannot contain duplicate keys.
You may not include the same header more than once.
Header keys cannot contain non-ASCII characters and empty spaces.
When defining the headers that you would like to use, you must make sure that the string contains only ASCII characters.
Header can not be one of the reserved keys.
Some header keys are reserved. You may not include any of the following reserved headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC.
\n\n\n\n\n

IP Pool Errors

\n\n\n\n\n

ip_pool_name

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The name of your IP pool must be a string.
The IP Pool name must be a valid pool name for your account. You provided [YOUR IP POOL NAME].
\n\n\n\n\n

Reply To Errors

\n\n\n\n\n

reply_to

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The reply_to object, when used, must at least have an email parameter with a valid email address and it may also contain a name parameter. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
For every carbon copy of your email, you must include one, valid recipient email address. However, you are not required to include a corresponding name with the recipient email address. For more information on how to use personalizations to define who you want to send your email to, please visit our Personalizations documentation.
\n\n\n\n\n

Sections Errors

\n\n\n\n\n

sections

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The section values must be strings.
The values of your sections parameter will be substituted into the content of your email. We will only perform substitutions using strings, so please make sure that your section values are always defined as strings.
\n\n\n\n\n

Send At Errors

\n\n\n\n\n

send_at

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The send_at parameter is expecting a Unix timestamp as an integer. We will send immediately if you include a send_at timestamp that is in the past.
send_at accepts a unix timestamp representing when you want your email to be sent from SendGrid. If you want the email to be sent at the time of your API request, simply omit the send_at parameter.
Scheduling more than 72 hours in advance is forbidden.
The send_at parameter allows you to schedule your email to be sent up to 72 hours in advance, but due to our constraints, we cannot schedule emails more than 72 hours in the future. For more information on scheduling parameters, please see our API Reference.
\n\n\n\n\n

Subject Line Errors

\n\n\n\n\n

subject

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subject of your email must be a string at least one character in length.
You are required to include a subject for every email you send, and you may not include an empty subject. The minimum length of your subject is one character.
The subject is required. You can get around this requirement if you use a template with a subject defined or if every personalization has a subject defined.
Every email must have a subject. This can be accomplished 3 ways: you include a template that has a subject, you define a global subject, or every single personalizations object has a subject.
\n\n\n\n\n

Template Errors

\n\n\n\n\n

template_id

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The template ID must be a string, you provided [YOUR TEMPLATE ID].
Template IDs are always strings.
The Template ID must be a valid template id for your account. You provided [YOUR TEMPLATE ID].
We do not allow you to send an empty email, so in the event that the only content of your email is contained within your template, we want to make sure that the included template exists, and is valid.
Must be a valid template.
We do not allow you to send an empty email, so in the event that the only content of your email is contained within your template, we want to make sure that the included template exists, and is valid.
\n\n\n\n\n

Mail Settings Errors

\n\n\n\n\n

mail_settings.bcc.email

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bcc email recipient object must at least have an email address and may also contain a name. e.g. {\"email\": \"example@example.com\"} or {\"email\": \"example@example.com\", \"name\": \"Example Recipient\"}
You must include a recipient object when using the bcc mail setting.
\n\n\n\n\n

mail_settings.bcc.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bcc enable param should be a boolean value.
\n\n\n\n\n

mail_settings.bypass_list_management.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The bypass list management enable param should be a boolean value.
\n\n\n\n\n

mail_settings.footer.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The footer enable param should be a boolean value.
\n\n\n\n\n

mail_settings.footer.html

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The text/html version of your footer should be a string.
\n\n\n\n\n

mail_settings.footer.text

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The text/plain version of your footer should be a string.
\n\n\n\n\n

mail_settings.sandbox_mode.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The sandbox mode enable param should be a boolean value.
\n\n\n\n\n

mail_settings.spam_check.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The spam check enable param should be a boolean value.
\n\n\n\n\n

mail_settings.spam_check.post_to_url

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The spam check url must be a string.
You must include the url to post to when using the spam check mail setting.
The `post_to_url` parameter must start with `http://` or `https://`.
\n\n\n\n\n

mail_settings.spam_check.threshold

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The spam check threshold is between 1 and 10, with the lower numbers being the most strict filtering.
You must include the spam check threshold when using the spam check mail setting.
\n\n\n\n\n

Tracking Settings Errors

\n\n\n\n\n

tracking_settings.click_tracking.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The click tracking enable param should be a boolean value.
\n\n\n\n\n

tracking_settings.click_tracking.enable_text

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The click tracking enable text must be a boolean value.
\n\n\n\n\n

tracking_settings.ganalytics.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics enable param must be a boolean value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_campaign

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_campaign must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_content

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_content must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_medium

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_medium must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_source

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_source must be a string value.
\n\n\n\n\n

tracking_settings.ganalytics.utm_term

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The Google Analytics utm_term must be a string value.
\n\n\n\n\n

tracking_settings.open_tracking.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The open tracking enable param should be a boolean value.
\n\n\n\n\n

tracking_settings.open_tracking.substitution_tag

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The open tracking substitution tag must be a string.
\n\n\n\n\n

tracking_settings.subscription_tracking.enable

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking enable param should be a boolean value.
\n\n\n\n\n

tracking_settings.subscription_tracking.html

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking unsubscribe content for text/html messages must be a string.
\n\n\n\n\n

tracking_settings.subscription_tracking.substitution_tag

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking substitution tag must be a string value.
\n\n\n\n\n

tracking_settings.subscription_tracking.text

\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n\n \n\n\n \n \n \n\n\n \n \n\n\n\n \n
Error CodeError MessageDetails
400
The subscription tracking unsubscribe content for text/plain messages must be a string.
\n\n\n\n\n\n ", + "public": true + }, + "api-key-permissions": { + "id": "api-key-permissions", + "name": "API Key Permissions", + "content": "API Keys can be used to authenticate the use of [SendGrid’s v3 API](https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access.\n\nThe following is a complete list of all possible permissions that you may assign to an API Key.\n\n* [Admin API Key Permissions](#Admin-API-Key-Permissions)\n* [Alerts](#Alerts)\n* [API Keys](#API-Keys)\n* [ASM Groups](#ASM-Groups)\n* [Billing](#Billing)\n* [Categories](#Categories)\n* [Clients](#Clients)\n* [Credentials](#Credentials)\n* [IPs](#IPs)\n* [Mail Settings](#Mail-Settings)\n* [Mail](#Mail)\n* [Marketing Campaigns](#Marketing-Campaigns)\n* [Partner Settings](#Partner-Settings)\n* [Scheduled Sends](#Scheduled-Sends)\n* [Stats](#Stats)\n* [Subusers](#Subusers)\n* [Suppressions](#Suppressions)\n* [Teammates](#Teammates)\n* [Templates](#Templates)\n* [Tracking](#Tracking)\n* [User Settings](#User-Settings)\n* [Webhook](#Webhook)\n* [Domain Authentication](#Domain-Authentication)\n* [Reverse DNS](#Reverse-DNS)\n\n\n

\n Admin API Key Permissions\n

\n\nBelow is a complete list of every API Key permission that should be given to an admin level API Key.\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\",\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\",\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\",\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\",\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\",\n \"browsers.stats.read\",\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\",\n \"categories.update\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\",\n \"credentials.create\",\n \"credentials.delete\",\n \"credentials.read\",\n \"credentials.update\",\n \"devices.stats.read\",\n \"email_activity.read\",\n \"geo.stats.read\",\n \"ips.assigned.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.read\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\",\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bcc.read\",\n \"mail_settings.bcc.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.plain_content.read\",\n \"mail_settings.plain_content.update\",\n \"mail_settings.read\",\n \"mail_settings.spam_check.read\",\n \"mail_settings.spam_check.update\",\n \"mail_settings.template.read\",\n \"mail_settings.template.update\",\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\",\n \"mailbox_providers.stats.read\",\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\",\n \"newsletter.create\",\n \"newsletter.delete\",\n \"newsletter.read\",\n \"newsletter.update\",\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\",\n \"partner_settings.sendwithus.read\",\n \"partner_settings.sendwithus.update\",\n \"stats.global.read\",\n \"stats.read\",\n \"subusers.create\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.credits.update\",\n \"subusers.delete\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.read\",\n \"subusers.reputations.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.read\",\n \"subusers.stats.sums.read\",\n \"subusers.summary.read\",\n \"subusers.update\",\n \"suppression.blocks.create\",\n \"suppression.blocks.delete\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.delete\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.delete\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.read\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.delete\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.delete\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.update\",\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\",\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\",\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.username.read\",\n \"user.username.update\",\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\",\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```\n\n\n

\n Alerts\n

\n\n```json\n\"scopes\": [\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\"\n]\n```\n\n\n

\n API Keys\n

\n\n```json\n\"scopes\": [\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\"\n]\n```\n\n

\n ASM Groups\n

\n\n```json\n\"scopes\": [\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\"\n]\n```\na>\n

\n Billing\n

\n\n**Billing permissions are mutually exclusive from all other permissions. An API Key can have *either* Billing Permissions *or* any other set of Permissions but not *both*.**\n\n```json\n\"scopes\": [\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\"\n]\n```\n\n\n

\n Categories\n

\n\n```json\n\"scopes\": [\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.update\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\"\n]\n```\n\n\n

\n Clients\n

\n\n```json\n\"scopes\": [\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\"\n]\n```\n\n\n

\n Credentials\n

\n\n```json\n\"scopes\": [\n \"credentials.create\",\n \"credentials.delete\",\n \"credentials.read\",\n \"credentials.update\"\n]\n```\n\n\n

\n IPs\n

\n\n```json\n\"scopes\": [\n \"ips.assigned.read\",\n \"ips.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\"\n]\n```\n\n\n

\n Mail Settings\n

\n\n```json\n\"scopes\": [\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bcc.read\",\n \"mail_settings.bcc.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.plain_content.read\",\n \"mail_settings.plain_content.update\",\n \"mail_settings.read\",\n \"mail_settings.spam_check.read\",\n \"mail_settings.spam_check.update\",\n \"mail_settings.template.read\",\n \"mail_settings.template.update\"\n]\n```\n\n\n

\n Mail\n

\n\n```json\n\"scopes\": [\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\"\n]\n```\n\n\n

\n Marketing Campaigns\n

\n\n```json\n\"scopes\": [\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\"\n]\n```\n\n\n

\n Newsletter\n

\n\n```json\n\"scopes\": [\n \"newsletter.create\",\n \"newsletter.delete\",\n \"newsletter.read\",\n \"newsletter.update\"\n]\n```\n\n\n

\n Partner-Settings\n

\n\n```json\n\"scopes\": [\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\",\n \"partner_settings.sendwithus.read\",\n \"partner_settings.sendwithus.update\"\n]\n```\n\na>\n

\n Scheduled Sends\n

\n\n```json\n\"scopes\": [\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\"\n]\n```\n\n\n

\n Stats\n

\n\n```json\n\"scopes\": [\n \"email_activity.read\",\n \"stats.read\",\n \"stats.global.read\",\n \"browsers.stats.read\",\n \"devices.stats.read\",\n \"geo.stats.read\",\n \"mailbox_providers.stats.read\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\"\n]\n```\n\n\n

\n Subusers\n

\n\n```json\n\"scopes\": [\n \"subusers.create\",\n \"subusers.delete\",\n \"subusers.read\",\n \"subusers.update\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.update\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.reputations.read\",\n \"subusers.stats.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.sums.read\"\n \"subusers.summary.read\"\n]\n```\n\n\n

\n Suppressions\n

\n\n```json\n\"scopes\": [\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.read\",\n \"suppression.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.bounces.delete\",\n \"suppression.blocks.create\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.blocks.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.invalid_emails.delete\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.spam_reports.delete\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.unsubscribes.delete\"\n]\n```\n\n\n

\n Teammates\n

\n\n```json\n\"scopes\": [\n \"teammates.create\",\n \"teammates.read\",\n \"teammates.update\",\n \"teammates.delete\"\n]\n```\n\n\n

\n Templates\n

\n\n```json\n\"scopes\": [\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\"\n]\n```\n\n\n

\n Tracking\n

\n\n```json\n\"scopes\": [\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\"\n]\n```\n\n\n

\n User Settings\n

\n\n```json\n\"scopes\": [\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.timezone.update\",\n \"user.username.read\",\n \"user.username.update\"\n]\n```\n\n\n

\n Webhook\n

\n\n```json\n\"scopes\": [\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\"\n]\n```\n\n\n

\n Domain Authentication (formerly Whitelabel)\n

\n\n```json\n\"scopes\": [\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```\n\n\n

\n Reverse DNS (formerly Whitelist)\n

\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\"\n]\n```", + "public": true + }, + "api-authorization": { + "id": "api-authorization", + "name": "Authorization", + "content": "# API Key Permissions List\n\nAPI Keys can be used to authenticate the use of SendGrid’s v3 Web API, or the [Mail API endpoint](https://sendgrid.com/docs/api-reference/). 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 permissions, please visit our [API Keys docs](https://sendgrid.com/docs/ui/account-and-settings/api-keys/). \n\nThe following is a complete list of all possible permissions that you may assign to an API Key.\n\n>When updating a key to include `user` or `subuser` scopes, use basic authenitcation.\n\n## Table of Contents\n\n\n\n\n\n\n\n\n\n\n
AlertsMail SettingsTeammates
API KeysMailTemplates
ASM GroupsMarketing CampaignsSuppressions
BillingPartner SettingsTracking
CategoriesScheduled SendsUser Settings
StatsWebhookIPs
SubusersDomain AuthenticationReverse DNS
Admin API Key Scopes
\n\n\n

Alerts

\n\n```json\n\"scopes\": [\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\"\n]\n```\n\n

API Keys

\n\n```json\n\"scopes\": [\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\"\n]\n```\n\n

ASM Groups

\n\n```json\n\"scopes\": [\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\"\n]\n```\n\n\n

Billing

\n\n```json\n\"scopes\": [\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\"\n]\n```\n\n\n**Billing permissions are mutually exclusive from all other permissions. An API Key can have *either* Billing Permissions *or* any other set of Permissions but not *both*.**\n\n\n

Categories

\n\n```json\n\"scopes\": [\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.update\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\"\n]\n```\n\n

Stats

\n\n```json\n\"scopes\": [\n \"email_activity.read\",\n \"stats.read\",\n \"stats.global.read\",\n \"browsers.stats.read\",\n \"devices.stats.read\",\n \"geo.stats.read\",\n \"mailbox_providers.stats.read\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\"\n]\n```\n\n

IPs

\n\n```json\n\"scopes\": [\n \"ips.assigned.read\",\n \"ips.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\"\n]\n```\n\n

Mail Settings

\n\n```json\n\"scopes\": [\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.template.read\",\n \"mail_settings.template.update\"\n]\n```\n\n

Mail

\n\n```json\n\"scopes\": [\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\"\n]\n```\n\n

Marketing Campaigns

\n\n```json\n\"scopes\": [\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\"\n]\n```\n\n\n

Partner Settings

\n\n```json\n\"scopes\": [\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\"\n]\n```\n\n

Scheduled Sends

\n\n```json\n\"scopes\": [\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\"\n]\n```\n\n

Subusers

\n\n```json\n\"scopes\": [\n \"subusers.create\",\n \"subusers.delete\",\n \"subusers.read\",\n \"subusers.update\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.update\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.reputations.read\",\n \"subusers.stats.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.sums.read\"\n \"subusers.summary.read\"\n]\n```\n\n

Suppressions

\n\n```json\n\"scopes\": [\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.read\",\n \"suppression.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.bounces.delete\",\n \"suppression.blocks.create\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.blocks.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.invalid_emails.delete\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.spam_reports.delete\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.unsubscribes.delete\"\n]\n```\n\n

Teammates

\n\n```json\n\"scopes\": [\n \"teammates.create\",\n \"teammates.read\",\n \"teammates.update\",\n \"teammates.delete\"\n]\n```\n\n

Templates

\n\n```json\n\"scopes\": [\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\"\n]\n```\n\n

Tracking

\n\n```json\n\"scopes\": [\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\"\n]\n```\n\n

User Settings

\n\n```json\n\"scopes\": [\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.timezone.update\",\n \"user.username.read\",\n \"user.username.update\"\n]\n```\n\n

Webhook

\n\n```json\n\"scopes\": [\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\"\n]\n```\n\n

Domain Authentication (formerly Whitelabel)

\n\n```json\n\"scopes\": [\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```\n\n

Reverse DNS (formerly Whitelist)

\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\"\n]\n```\n\n

Admin API Key Scopes

\n\nBelow is a complete list of every API Key scope to be given to an admin level API Key.\n\n```json\n\"scopes\": [\n \"access_settings.activity.read\",\n \"access_settings.whitelist.create\",\n \"access_settings.whitelist.delete\",\n \"access_settings.whitelist.read\",\n \"access_settings.whitelist.update\",\n \"alerts.create\",\n \"alerts.delete\",\n \"alerts.read\",\n \"alerts.update\",\n \"api_keys.create\",\n \"api_keys.delete\",\n \"api_keys.read\",\n \"api_keys.update\",\n \"asm.groups.create\",\n \"asm.groups.delete\",\n \"asm.groups.read\",\n \"asm.groups.update\",\n \"billing.create\",\n \"billing.delete\",\n \"billing.read\",\n \"billing.update\",\n \"browsers.stats.read\",\n \"categories.create\",\n \"categories.delete\",\n \"categories.read\",\n \"categories.stats.read\",\n \"categories.stats.sums.read\",\n \"categories.update\",\n \"clients.desktop.stats.read\",\n \"clients.phone.stats.read\",\n \"clients.stats.read\",\n \"clients.tablet.stats.read\",\n \"clients.webmail.stats.read\",\n \"devices.stats.read\",\n \"email_activity.read\",\n \"geo.stats.read\",\n \"ips.assigned.read\",\n \"ips.pools.create\",\n \"ips.pools.delete\",\n \"ips.pools.ips.create\",\n \"ips.pools.ips.delete\",\n \"ips.pools.ips.read\",\n \"ips.pools.ips.update\",\n \"ips.pools.read\",\n \"ips.pools.update\",\n \"ips.read\",\n \"ips.warmup.create\",\n \"ips.warmup.delete\",\n \"ips.warmup.read\",\n \"ips.warmup.update\",\n \"mail_settings.address_whitelist.read\",\n \"mail_settings.address_whitelist.update\",\n \"mail_settings.bounce_purge.read\",\n \"mail_settings.bounce_purge.update\",\n \"mail_settings.footer.read\",\n \"mail_settings.footer.update\",\n \"mail_settings.forward_bounce.read\",\n \"mail_settings.forward_bounce.update\",\n \"mail_settings.forward_spam.read\",\n \"mail_settings.forward_spam.update\",\n \"mail_settings.plain_content.read\",\n \"mail_settings.plain_content.update\",\n \"mail_settings.read\",,\n \"mail_settings.template.read\",\n \"mail_settings.template.update\",\n \"mail.batch.create\",\n \"mail.batch.delete\",\n \"mail.batch.read\",\n \"mail.batch.update\",\n \"mail.send\",\n \"mailbox_providers.stats.read\",\n \"marketing_campaigns.create\",\n \"marketing_campaigns.delete\",\n \"marketing_campaigns.read\",\n \"marketing_campaigns.update\",\n \"partner_settings.new_relic.read\",\n \"partner_settings.new_relic.update\",\n \"partner_settings.read\",\n \"stats.global.read\",\n \"stats.read\",\n \"subusers.create\",\n \"subusers.credits.create\",\n \"subusers.credits.delete\",\n \"subusers.credits.read\",\n \"subusers.credits.remaining.create\",\n \"subusers.credits.remaining.delete\",\n \"subusers.credits.remaining.read\",\n \"subusers.credits.remaining.update\",\n \"subusers.credits.update\",\n \"subusers.delete\",\n \"subusers.monitor.create\",\n \"subusers.monitor.delete\",\n \"subusers.monitor.read\",\n \"subusers.monitor.update\",\n \"subusers.read\",\n \"subusers.reputations.read\",\n \"subusers.stats.monthly.read\",\n \"subusers.stats.read\",\n \"subusers.stats.sums.read\",\n \"subusers.summary.read\",\n \"subusers.update\",\n \"suppression.blocks.create\",\n \"suppression.blocks.delete\",\n \"suppression.blocks.read\",\n \"suppression.blocks.update\",\n \"suppression.bounces.create\",\n \"suppression.bounces.delete\",\n \"suppression.bounces.read\",\n \"suppression.bounces.update\",\n \"suppression.create\",\n \"suppression.delete\",\n \"suppression.invalid_emails.create\",\n \"suppression.invalid_emails.delete\",\n \"suppression.invalid_emails.read\",\n \"suppression.invalid_emails.update\",\n \"suppression.read\",\n \"suppression.spam_reports.create\",\n \"suppression.spam_reports.delete\",\n \"suppression.spam_reports.read\",\n \"suppression.spam_reports.update\",\n \"suppression.unsubscribes.create\",\n \"suppression.unsubscribes.delete\",\n \"suppression.unsubscribes.read\",\n \"suppression.unsubscribes.update\",\n \"suppression.update\",\n \"teammates.create\",\n \"teammates.read\",\n \"teammates.update\",\n \"teammates.delete\",\n \"templates.create\",\n \"templates.delete\",\n \"templates.read\",\n \"templates.update\",\n \"templates.versions.activate.create\",\n \"templates.versions.activate.delete\",\n \"templates.versions.activate.read\",\n \"templates.versions.activate.update\",\n \"templates.versions.create\",\n \"templates.versions.delete\",\n \"templates.versions.read\",\n \"templates.versions.update\",\n \"tracking_settings.click.read\",\n \"tracking_settings.click.update\",\n \"tracking_settings.google_analytics.read\",\n \"tracking_settings.google_analytics.update\",\n \"tracking_settings.open.read\",\n \"tracking_settings.open.update\",\n \"tracking_settings.read\",\n \"tracking_settings.subscription.read\",\n \"tracking_settings.subscription.update\",\n \"user.account.read\",\n \"user.credits.read\",\n \"user.email.create\",\n \"user.email.delete\",\n \"user.email.read\",\n \"user.email.update\",\n \"user.multifactor_authentication.create\",\n \"user.multifactor_authentication.delete\",\n \"user.multifactor_authentication.read\",\n \"user.multifactor_authentication.update\",\n \"user.password.read\",\n \"user.password.update\",\n \"user.profile.read\",\n \"user.profile.update\",\n \"user.scheduled_sends.create\",\n \"user.scheduled_sends.delete\",\n \"user.scheduled_sends.read\",\n \"user.scheduled_sends.update\",\n \"user.settings.enforced_tls.read\",\n \"user.settings.enforced_tls.update\",\n \"user.timezone.read\",\n \"user.username.read\",\n \"user.username.update\",\n \"user.webhooks.event.settings.read\",\n \"user.webhooks.event.settings.update\",\n \"user.webhooks.event.test.create\",\n \"user.webhooks.event.test.read\",\n \"user.webhooks.event.test.update\",\n \"user.webhooks.parse.settings.create\",\n \"user.webhooks.parse.settings.delete\",\n \"user.webhooks.parse.settings.read\",\n \"user.webhooks.parse.settings.update\",\n \"user.webhooks.parse.stats.read\",\n \"whitelabel.create\",\n \"whitelabel.delete\",\n \"whitelabel.read\",\n \"whitelabel.update\"\n]\n```", + "public": true + }, + "on-behalf-of": { + "id": "on-behalf-of", + "name": "On Behalf of Subuser", + "content": "Use the *on-behalf-of* header to make calls for a particular subuser through the parent account. Use this header to automate bulk updates, or to administer a subuser without changing the authentication in your code.\n\nTo use the feature, add the *on-behalf-of* header:\n\n`on-behalf-of: << subuser username >>`\n\nThis header generates the API call as if the subuser account was making the call.\n\nWhen authenticating using the *on-behalf-of* header, you need to use the API key credentials of the **parent account**. For example:\n\n```curl --request GET \\\n --url 'https://api.sendgrid.com/v3/stats?start_date=2018-02-01&aggregated_by=day' \\\n --header 'authorization: Bearer << API KEY >>' \\\n --header 'on-behalf-of: << subuser username >>'\n ```\n\n**Note**: The *on-behalf-of* header does not work with the mail.send API.", + "public": true + } + }, + "mock": { + "enabled": false, + "dynamic": false + } + }, + "x-tests": { + "2QtdGPeZcwPm7CTTh": { + "id": "2QtdGPeZcwPm7CTTh", + "name": "Alerts test", + "initialVariables": {}, + "steps": [ + { + "id": "LrnrTjuMQ2kCb9xZG", + "name": "Create a new Alert", + "beforeScript": null, + "afterScript": null, + "capture": { + "body": [ + { + "name": "alert_id", + "value": "id" + } + ] + }, + "request": { + "queryString": [], + "postData": { + "mimeType": "application/json", + "params": [], + "text": "{\n \"type\": \"stats_notification\",\n \"email_to\": \"example@example.com\",\n \"frequency\": \"daily\"\n}" + }, + "authentication": {}, + "method": "post", + "url": "/alerts", + "headers": [ + { + "value": "Bearer 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", + "name": "Authorization" + } + ], + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 201 + }, + { + "op": "validate.pass", + "match": 201, + "location": "response.body" + } + ] + }, + { + "id": "aRd37ou83TsrHxkMc", + "name": "Retrieve a specific alert", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "method": "get", + "url": "/alerts/{alert_id}", + "headers": [ + { + "name": "Authorization", + "value": "Bearer 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" + } + ], + "queryString": [], + "postData": {}, + "authentication": {}, + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 200 + }, + { + "op": "validate.pass", + "match": 200, + "location": "response.body" + } + ] + }, + { + "id": "nqDiBRakuZA8nD6s7", + "name": "Update an alert", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "method": "patch", + "url": "/alerts/{alert_id}", + "headers": [ + { + "name": "Authorization", + "value": "Bearer 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" + } + ], + "queryString": [], + "postData": { + "mimeType": "application/json", + "params": [], + "text": "{\n \"email_to\": \"matt@example.com\"\n}" + }, + "authentication": {}, + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 200 + }, + { + "op": "validate.pass", + "match": 200, + "location": "response.body" + } + ] + }, + { + "id": "MvuQwBuikXtWbsCBt", + "name": "Delete an alert", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "method": "delete", + "url": "/alerts/{alert_id}", + "headers": [ + { + "name": "Authorization", + "value": "Bearer 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" + } + ], + "queryString": [], + "postData": {}, + "authentication": {}, + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 204 + }, + { + "op": "validate.pass", + "match": 204, + "location": "response.body" + } + ] + }, + { + "id": "kuh6nzo9sAfXJeSzz", + "name": "shitty response", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "authentication": {}, + "method": "post", + "url": "/alerts", + "headers": [ + { + "name": "Authorization", + "value": "Bearer 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" + } + ], + "queryString": [], + "postData": { + "mimeType": "application/json", + "params": [], + "text": "{\n \"type\": \"bullshit\",\n \"email_to\": \"example@example.com\",\n \"frequency\": \"daily\"\n}" + }, + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 400 + }, + { + "op": "validate.pass", + "match": 400, + "location": "response.body" + } + ] + } + ] + }, + "HFGvnuoqkd36FarWE": { + "id": "HFGvnuoqkd36FarWE", + "name": "Parse Settings Test", + "initialVariables": {}, + "steps": [ + { + "id": "DXFjNLuibt8mBTMDE", + "name": "Create a parse setting", + "beforeScript": null, + "afterScript": null, + "capture": { + "body": [ + { + "name": "hostname", + "value": "hostname" + } + ] + }, + "request": { + "method": "post", + "url": "/user/webhooks/parse/settings", + "headers": [ + { + "name": "Authorization", + "value": "Bearer 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" + } + ], + "queryString": [], + "postData": { + "mimeType": "application/json", + "params": [], + "text": "{\n \"hostname\": \"manbearpig.com\",\n \"url\": \"http://email.manbearpig.com\",\n \"spam_check\": true,\n \"send_raw\": false\n}" + }, + "authentication": {}, + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 201 + }, + { + "op": "validate.pass", + "match": 201, + "location": "response.body" + } + ] + }, + { + "id": "6DoSn3KYqs3LqNzo4", + "name": "Retrieve all parse settings", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "method": "get", + "url": "/user/webhooks/parse/settings", + "headers": [ + { + "value": "Bearer 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", + "name": "Authorization" + } + ], + "queryString": [], + "postData": {}, + "authentication": {}, + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 200 + }, + { + "op": "validate.pass", + "match": 200, + "location": "response.body" + } + ] + }, + { + "id": "sXYsGopzxCdmtFBpf", + "name": "Retrieve a specific parse setting", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "postData": {}, + "authentication": {}, + "method": "get", + "url": "/user/webhooks/parse/settings/{hostname}", + "headers": [ + { + "value": "Bearer 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", + "name": "Authorization" + } + ], + "queryString": [], + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 200 + }, + { + "op": "validate.pass", + "match": 200, + "location": "response.body" + } + ] + }, + { + "id": "AL2R3B5fyfMcLKvFg", + "name": "Update a parse setting", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "method": "patch", + "url": "/user/webhooks/parse/settings/{hostname}/", + "headers": [ + { + "name": "Authorization", + "value": "Bearer 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" + } + ], + "queryString": [], + "postData": { + "text": "{\n \"url\": \"http://newdomain.com/parse\",\n \"spam_check\": false,\n \"send_raw\": true\n}", + "mimeType": "application/json", + "params": [] + }, + "authentication": {}, + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 200 + }, + { + "op": "validate.pass", + "match": 200, + "location": "response.body" + } + ] + }, + { + "id": "7ewLowiXP3fFti63Z", + "name": "Verify updating a parse setting", + "beforeScript": null, + "afterScript": "function (ctx, request, response) {\n // Your javascript code here.\n // Code completion enabled.\n // You have access to a global \"SL\" object.\n // \"url\": \"http://newdomain.com/parse\",\n // \"spam_check\": false,\n // \"send_raw\": true\n var body = response.body.get();\n assert.equal(body.url, \"http://newdomain.com/parse\");\n assert.equal(body.spam_check, false);\n assert.equal(body.send_raw, true);\n}", + "capture": {}, + "request": { + "url": "/user/webhooks/parse/settings/{hostname}", + "headers": [ + { + "name": "Authorization", + "value": "Bearer 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" + } + ], + "queryString": [], + "postData": {}, + "authentication": {}, + "method": "get", + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 200 + }, + { + "op": "validate.pass", + "match": 200, + "location": "response.body" + } + ] + }, + { + "id": "738KySxu4mWHjDvmw", + "name": "Delete a parse setting", + "beforeScript": null, + "afterScript": null, + "capture": {}, + "request": { + "postData": { + "text": "{}", + "mimeType": "application/json", + "params": [] + }, + "authentication": {}, + "method": "delete", + "url": "/user/webhooks/parse/settings/{hostname}", + "headers": [ + { + "value": "Bearer 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", + "name": "Authorization" + } + ], + "queryString": [], + "valid": 2, + "transformed": false, + "pathParams": [], + "cookies": [], + "headersSize": -1, + "bodySize": -1 + }, + "assertions": [ + { + "op": "eq", + "location": "response.code", + "expected": 204 + }, + { + "op": "validate.pass", + "match": 204, + "location": "response.body" + } + ] + } + ] + } } } \ No newline at end of file