{ "swagger": "2.0", "info": { "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" ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "securityDefinitions": { "Authorization": { "name": "Authorization", "type": "apiKey", "in": "header" } }, "paths": { "/mail/send": { "post": { "operationId": "POST_mail-send", "summary": "v3 Mail Send", "tags": [ "Mail Send" ], "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\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:\n\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`\n\n## Multiple Reply-To Emails\n\nUsing `reply_to_list` allows senders to include more than one recipient email address to receive reply and/or bounce messages from the recipient of the email.\n\n### Usage Considerations\n\n* `reply_to` is mutually exclusive with `reply_to_list`. If both are used, then the API call will be rejected. \n* The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter.\n* Each email address in the `reply_to_list` should be unique.\n* There is a limit of 1000 `reply_to_list` emails per mail/send request.\n* In SMTP calls, we will omit any invalid emails.\n\n### Possible 400 Error Messages\n\n* `reply_to` is mutually exclusive with `reply_to_list`.\n* The `reply_to_list` object, when used, must at least have an email parameter and may also contain a name parameter.\n* Each email address in the `reply_to_list` should be unique.\n* There is a limit of X `reply_to` emails per mail/send request.\n* The `reply_to_list` email does not contain a valid address.\n* The `reply_to_list` email exceeds the maximum total length of X characters.\n* The `reply_to_list` email parameter is required.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "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. 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": { "$ref": "#/definitions/to_email_array" }, "cc": { "type": "array", "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 recipient's name.", "maxItems": 1000, "items": { "$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 in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name.", "maxItems": 1000, "items": { "$ref": "#/definitions/cc_bcc_email_object" } }, "subject": { "type": "string", "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 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": "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. This field may not exceed 10,000 bytes.", "maxProperties": 10000 }, "send_at": { "type": "integer", "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": [ "to" ] } }, "from": { "$ref": "#/definitions/from_email_object" }, "reply_to": { "$ref": "#/definitions/reply_to_email_object" }, "reply_to_list": { "type": "array", "description": "An array of recipients who will receive replies and/or bounces. Each object in this array must contain the recipient's email address. Each object in the array may optionally contain the recipient's name. You can either choose to use “reply_to” field or “reply_to_list” but not both.", "uniqueItems": true, "maxItems": 1000, "items": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address where any replies or bounces will be returned.", "format": "email" }, "name": { "type": "string", "description": "A name or title associated with the `reply_to_list` email address." } }, "required": [ "email" ] } }, "subject": { "type": "string", "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 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 (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.", "minLength": 1 } }, "required": [ "type", "value" ] } }, "attachments": { "type": "array", "description": "An array of objects where you can specify any attachments you want to include.", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "The Base64 encoded content of the attachment.", "minLength": 1 }, "type": { "type": "string", "description": "The MIME type of the content you are attaching (e.g., `“text/plain”` or `“text/html”`).", "minLength": 1 }, "filename": { "type": "string", "description": "The attachment's filename." }, "disposition": { "type": "string", "default": "attachment", "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" ] }, "content_id": { "type": "string", "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": [ "content", "filename" ] } }, "template_id": { "type": "string", "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": { "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", "description": "An array of category names for this message. Each category name may not exceed 255 characters. ", "uniqueItems": true, "maxItems": 10, "items": { "type": "string", "maxLength": 255 } }, "custom_args": { "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 `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": "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", "description": "An object allowing you to specify how to handle unsubscribes.", "properties": { "group_id": { "type": "integer", "description": "The unsubscribe group to associate with this email." }, "groups_to_display": { "type": "array", "description": "An array containing the unsubscribe groups that you would like to be displayed on the unsubscribe preferences page.", "maxItems": 25, "items": { "type": "integer" } } }, "required": [ "group_id" ] }, "ip_pool_name": { "type": "string", "description": "The IP Pool that you would like to send this email from.", "minLength": 2, "maxLength": 64 }, "mail_settings": { "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": { "bypass_list_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. 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." } } }, "bypass_spam_management": { "type": "object", "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", "description": "Indicates if this setting is enabled." } } }, "bypass_bounce_management": { "type": "object", "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." } } }, "bypass_unsubscribe_management": { "type": "object", "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", "description": "Indicates if this setting is enabled." } } }, "footer": { "type": "object", "description": "The default footer that you would like included on every email.", "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": { "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." } } } } }, "tracking_settings": { "type": "object", "description": "Settings to determine how you would like to track the metrics of how your recipients interact with your email.", "properties": { "click_tracking": { "type": "object", "description": "Allows you to track if a recipient clicked a link in your email.", "properties": { "enable": { "type": "boolean", "description": "Indicates if this setting is enabled." }, "enable_text": { "type": "boolean", "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 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", "description": "Indicates if this setting is enabled." }, "substitution_tag": { "type": "string", "description": "Allows you to specify a substitution tag that you can insert in the body of your email at a location that you desire. This tag will be replaced by the open tracking pixel." } } }, "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`.", "properties": { "enable": { "type": "boolean", "description": "Indicates if this setting is enabled." }, "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 <% %>" }, "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 <% %>" }, "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." } } }, "ganalytics": { "type": "object", "description": "Allows you to enable tracking provided by Google Analytics.", "properties": { "enable": { "type": "boolean", "description": "Indicates if this setting is enabled." }, "utm_source": { "type": "string", "description": "Name of the referrer source. (e.g. Google, SomeDomain.com, or Marketing Email)" }, "utm_medium": { "type": "string", "description": "Name of the marketing medium. (e.g. Email)" }, "utm_term": { "type": "string", "description": "Used to identify any paid keywords." }, "utm_content": { "type": "string", "description": "Used to differentiate your campaign from advertisements." }, "utm_campaign": { "type": "string", "description": "The name of the campaign." } } } } } }, "required": [ "personalizations", "from", "subject", "content" ], "example": { "personalizations": [ { "to": [ { "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" } ], "bcc": [ { "email": "jordan_doe@example.com", "name": "Jordan Doe" } ] } ], "from": { "email": "orders@example.com", "name": "Example Order Confirmation" }, "reply_to": { "email": "customer_service@example.com", "name": "Example Customer Service Team" }, "subject": "Your Example Order Confirmation", "content": [ { "type": "text/html", "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": "" }, "400": { "$ref": "#/responses/trait:mailSendErrors:400" }, "401": { "$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/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": [] } ] } }, "/user/scheduled_sends": { "post": { "operationId": "POST_user-scheduled_sends", "summary": "Cancel or pause a scheduled send", "tags": [ "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": { "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" ], "example": { "batch_id": "YOUR_BATCH_ID", "status": "pause" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/user_scheduled_send_status" } }, "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": [] } ] }, "get": { "operationId": "GET_user-scheduled_sends", "summary": "Retrieve all scheduled sends", "tags": [ "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": [ { "$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": "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": [] } ] } }, "/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", "tags": [ "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": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$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": [] } ] } }, "/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": [ "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": { "200": { "description": "", "schema": { "type": "array", "title": "Retrieve scheduled send response", "items": { "$ref": "#/definitions/user_scheduled_send_status" } }, "examples": { "application/json": [ { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", "status": "cancel" }, { "batch_id": "IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg", "status": "pause" } ] } }, "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_user-scheduled_sends-batch_id", "summary": "Update a scheduled send", "tags": [ "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", "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" ], "example": { "status": "pause" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "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": [] } ] }, "delete": { "operationId": "DELETE_user-scheduled_sends-batch_id", "summary": "Delete a cancellation or pause from a scheduled send", "tags": [ "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": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "" }, "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": { "post": { "operationId": "create-api-keys", "summary": "Create API keys", "tags": [ "API Keys" ], "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", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name you will use to describe this API Key." }, "scopes": { "type": "array", "description": "The individual permissions that you are giving to this API Key.", "items": { "type": "string" } } }, "required": [ "name" ], "example": { "name": "My API Key", "scopes": [ "mail.send", "alerts.create", "alerts.read" ] } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "api_key_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "examples": { "application/json": { "api_key": "SG.xxxxxxxx.yyyyyyyy", "api_key_id": "xxxxxxxx", "name": "My API Key", "scopes": [ "mail.send", "alerts.create", "alerts.read" ] } } }, "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": [] } ] }, "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": { "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" } ] } } }, "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/{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 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" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/definitions/api_key_name_id_scopes" } } } }, "examples": { "application/json": { "result": [ { "name": "API Key Name", "api_key_id": "some-apikey-id" }, { "name": "API Key Name 2", "api_key_id": "another-apikey-id" } ] } } }, "400": { "$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 key name", "tags": [ "API Keys" ], "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", "in": "body", "schema": { "type": "object", "properties": { "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" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/api_key_name_id" }, "examples": { "application/json": { "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", "name": "A New Hope" } } }, "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": [] } ] }, "put": { "operationId": "PUT_api_keys-api_key_id", "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\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", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ], "example": { "name": "Profiles key", "scopes": [ "user.profile.read", "user.profile.update" ] } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/api_key_name_id_scopes" }, "examples": { "application/json": { "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", "name": "Profiles Key", "scopes": [ "user.profile.read", "user.profile.update" ] } } }, "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_api_keys-api_key_id", "summary": "Delete API keys", "tags": [ "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": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "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": [ { "Authorization": [] } ] } }, "/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 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": [ { "$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": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes.", "items": { "type": "object", "properties": { "field": { "type": "null", "description": "This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required." }, "message": { "type": "string", "description": "Explains why the scopes cannot be returned." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "403": { "$ref": "#/responses/trait:globalErrors:403" }, "404": { "$ref": "#/responses/trait:globalErrors:404" }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] } }, "/user/settings/enforced_tls": { "get": { "operationId": "GET_user-settings-enforced_tls", "summary": "Retrieve current Enforced TLS settings.", "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.\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": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/enforced-tls-request-response" }, "examples": { "application/json": { "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.**\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": { "$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 \"Retrieve a list of currently allowed IPs\" endpoint.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "ips": { "type": "array", "description": "An array containing the IP(s) you want to allow.", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "An IP address that you want to allow." } }, "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": { "$ref": "#/definitions/ip-access-response" }, "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 } ] } } }, "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_access_settings-whitelist", "summary": "Retrieve a list of currently allowed IPs", "tags": [ "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" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip-access-response" }, "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 } ] } } }, "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_access_settings-whitelist", "summary": "Remove one or more IPs from the allow list", "tags": [ "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 \"Retrieve a list of currently allowed IPs\" endpoint.\n\nIt is possible to remove your own IP address, which will block access to your account. You will need to submit a [support ticket](https://sendgrid.com/docs/ui/account-and-settings/support/) if this happens. For this reason, it is important to double check that you are removing only the IPs you intend to remove when using this endpoint.", "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 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": { "$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_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.**", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of IPs to return.", "type": "integer", "default": 20 }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "array", "description": "An array containing the IPs that recently attempted to access your account.", "items": { "type": "object", "properties": { "allowed": { "type": "boolean", "description": "Indicates if the IP address was granted access to the account." }, "auth_method": { "type": "string", "description": "The authentication method used when attempting access." }, "first_at": { "type": "integer", "description": "A Unix timestamp indicating when the first access attempt was made." }, "ip": { "type": "string", "description": "The IP addressed used during the access attempt." }, "last_at": { "type": "integer", "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": [ { "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": [] } ] } }, "/access_settings/whitelist/{rule_id}": { "parameters": [ { "name": "rule_id", "in": "path", "description": "The ID of the allowed IP address that you want to retrieve.", "required": true, "type": "string" } ], "get": { "operationId": "GET_access_settings-whitelist-rule_id", "summary": "Retrieve a specific allowed IP", "tags": [ "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 \"Retrieve a list of currently allowed IPs\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip-access-response" }, "examples": { "application/json": { "id": 1, "ip": "192.168.1.1", "created_at": 1441824715, "updated_at": 1441824715 } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_access_settings-whitelist-rule_id", "summary": "Remove a specific IP from the allowed list", "tags": [ "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 \"Retrieve a list of currently allowed IPs\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "object", "properties": {} } } }, "security": [ { "Authorization": [] } ] } }, "/sso/certificates": { "post": { "operationId": "POST_sso-certificates", "summary": "Create an SSO Certificate", "tags": [ "Certificates" ], "description": "**This endpoint allows you to create an SSO certificate.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "description": "", "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 if the certificate is enabled." }, "integration_id": { "type": "string", "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": [ "public_certificate", "integration_id" ], "example": { "public_certificate": "<% 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/mail_settings_template" }, "examples": { "application/json": { "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": [] } ] } }, "/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.**\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": { "$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/mail_settings_bounce_purge" }, "examples": { "application/json": { "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": [] } ] }, "get": { "operationId": "GET_mail_settings-bounce_purge", "summary": "Retrieve bounce purge mail settings", "tags": [ "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": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/mail_settings_bounce_purge" }, "examples": { "application/json": { "enabled": false, "soft_bounces": 5, "hard_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": [] } ] } }, "/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": { "$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": { "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.**\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": [ { "$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" } } }, "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": [] } ] } }, "/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": "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" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/partner_settings_new_relic" }, "examples": { "application/json": { "enable_subuser_statistics": true, "enabled": true, "license_key": "" } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_partner_settings-new_relic", "summary": "Returns all New Relic partner settings.", "tags": [ "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": [ { "$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.**\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" } ], "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", "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" } ], "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": { "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" } } } } } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_v3-teammates", "summary": "Retrieve all teammates", "tags": [ "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" } ], "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" } } } } } }, "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": [] } ] } }, "/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 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" } ], "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.**\n\nThe Response Header's `link` parameter will include pagination info.", "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" }, { "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_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\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" } ], "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" } } } } } }, "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/{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.**\n\nYou can retrieve the username's for each of your Teammates using the \"Retrieve all Teammates\" endpoint.", "parameters": [ { "$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" }, "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", "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.**", "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 } } }, { "$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" } } }, "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" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "username not found", "field": "username" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_v3-teammates-username", "summary": "Delete teammate", "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.**", "parameters": [ { "$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": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "username not found", "field": "username" } ] } } } }, "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.", "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": [] } ] } }, "/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.", "responses": { "204": { "description": "" }, "401": { "description": "" }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "Cannot find request", "field": "request_id" } ] } } } }, "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.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "" }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } } } }, "security": [ { "Authorization": [] } ] } }, "/alerts": { "post": { "operationId": "POST_alerts", "summary": "Create a new Alert", "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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "name": "body", "in": "body", "schema": { "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" } } }, { "name": "Authorization", "in": "header", "type": "string" }, { "name": "on-behalf-of", "in": "header", "type": "string" } ], "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.", "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": { "created_at": 1451520930, "email_to": "test@example.com", "frequency": "daily", "id": 48, "type": "stats_notification", "updated_at": 1451520930 } } }, "400": { "description": "", "schema": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_alerts", "summary": "Retrieve all alerts", "tags": [ "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": "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" ] } }, "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 } ] } } }, "security": [ { "Authorization": [] } ] } }, "/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_alerts-alert_id", "summary": "Retrieve a specific alert", "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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "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" ] }, "examples": { "application/json": { "created_at": 1451520930, "email_to": "example@example.com", "frequency": "daily", "id": 48, "type": "stats_notification", "updated_at": 1451520930 } } } }, "security": [ { "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": { "204": { "description": "", "schema": { "type": "object", "properties": {} } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_alerts-alert_id", "summary": "Update an alert", "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 [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "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.\nExample: test@example.com" }, "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" } } }, { "$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" ] }, "examples": { "application/json": { "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": { "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": { "$ref": "#/definitions/user_profile", "example": { "first_name": "Example", "last_name": "User", "city": "Orange" } } }, { "$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": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "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.**\n\nYour user's account information includes the user's account type and reputation.", "parameters": [ { "$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" ] }, "examples": { "application/json": { "reputation": 100, "type": "paid" } } } }, "security": [ { "Authorization": [] } ] } }, "/user/email": { "get": { "operationId": "GET_user-email", "summary": "Retrieve your account email address", "tags": [ "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" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address currently on file for your account.", "format": "email" } }, "required": [ "email" ] }, "examples": { "application/json": { "email": "test@example.com" } } } }, "security": [ { "Authorization": [] } ] }, "put": { "operationId": "PUT_user-email", "summary": "Update your account email address", "tags": [ "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": "object", "properties": { "email": { "type": "string", "description": "The new email address that you would like to use for your account." } }, "example": { "email": "example@example.com" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The current email address on file for your account.", "format": "email" } }, "required": [ "email" ] }, "examples": { "application/json": { "email": "example@example.com" } } } }, "security": [ { "Authorization": [] } ] } }, "/user/username": { "get": { "operationId": "GET_user-username", "summary": "Retrieve your username", "tags": [ "Users API" ], "description": "**This endpoint allows you to retrieve your current account username.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "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", "tags": [ "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" } ], "responses": { "200": { "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" } } } }, "security": [ { "Authorization": [] } ] } }, "/user/credits": { "get": { "operationId": "GET_user-credits", "summary": "Retrieve your credit balance", "tags": [ "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" } ], "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" ] }, "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": [ { "Authorization": [] } ] } }, "/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_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" }, { "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": { "type": "array", "items": { "$ref": "#/definitions/subuser" } }, "examples": { "application/json": [ { "disabled": false, "email": "example@example.com", "id": 1234, "username": "example_subuser" }, { "disabled": false, "email": "example2@example.com", "id": 1234, "username": "example_subuser2" } ] } }, "401": { "description": "Unexpected error in API call. See HTTP response body for details.", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "post": { "operationId": "POST_subusers", "summary": "Create Subuser", "tags": [ "Subusers API" ], "description": "**This endpoint allows you to create a new subuser.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The username for this subuser." }, "email": { "type": "string", "description": "The email address of the subuser.", "format": "email" }, "password": { "type": "string", "description": "The password this subuser will use when logging into SendGrid." }, "ips": { "type": "array", "description": "The IP addresses that should be assigned to this subuser.", "items": { "type": "string", "format": "ipv4" } } }, "required": [ "username", "email", "password", "ips" ], "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/subuser_post" }, "examples": { "application/json": { "username": "example_subuser", "user_id": 1234, "email": "example@example.com", "signup_session_token": "", "authorization_token": "", "credit_allocation": { "type": "unlimited" } } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "username exists" }, { "message": "unable to validate IPs at this time" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "403": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "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" } ] } } } }, "security": [ { "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", "tags": [ "Subusers API" ], "description": "**This endpoint allows you to enable or disable a subuser.**", "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 } } } ], "responses": { "204": { "description": "", "schema": { "type": "object", "properties": {} } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "invalid username" }, { "message": "no fields provided" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "500": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "unable to enable user" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_subusers-subuser_name", "summary": "Delete a subuser", "tags": [ "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": { "204": { "description": "", "schema": { "type": "object", "properties": {} } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "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": { "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 } ] } } }, "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", "tags": [ "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": "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": { "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_error_response_schema" }, "examples": { "application/json": { "errors": [ { "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_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": [] } ] }, "post": { "operationId": "POST_subusers-subuser_name-monitor", "summary": "Create monitor settings", "tags": [ "Subuser Monitor Settings" ], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/monitor", "example": { "email": "example@example.com", "frequency": 50000 } } } ], "responses": { "200": { "description": "", "schema": { "$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" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "put": { "operationId": "PUT_subusers-subuser_name-monitor", "summary": "Update Monitor Settings for a subuser", "tags": [ "Subuser Monitor Settings" ], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/monitor", "example": { "email": "example@example.com", "frequency": 500 } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/monitor" }, "examples": { "application/json": { "email": "example@example.com", "frequency": 500 } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "email", "message": "Email is required" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_subusers-subuser_name-monitor", "summary": "Delete monitor settings", "tags": [ "Subuser Monitor Settings" ], "responses": { "204": { "description": "", "schema": { "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": [] } ] } }, "/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": [ "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": "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": { "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": [] } ] } }, "/subusers/stats/monthly": { "get": { "operationId": "GET_subusers-stats-monthly", "summary": "Retrieve monthly stats for all subusers", "tags": [ "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": [ { "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": { "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": "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": { "200": { "description": "", "schema": { "$ref": "#/definitions/category_stats" }, "examples": { "application/json": { "date": "2015-10-11", "stats": [] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/stats": { "get": { "operationId": "GET_subusers-stats", "summary": "Retrieve email statistics for your subusers.", "tags": [ "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": "limit", "in": "query", "description": "Limits the number of results returned per page.", "required": false, "type": "integer" }, { "name": "offset", "in": "query", "description": "The point in the list to begin retrieving results from.", "required": false, "type": "integer" }, { "name": "aggregated_by", "in": "query", "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", "required": false, "type": "string", "enum": [ "day", "week", "month" ] }, { "name": "subusers", "in": "query", "description": "The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "The end date of the statistics to retrieve. Defaults to today.", "required": false, "type": "string" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/category_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 } } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links": { "post": { "operationId": "POST_whitelabel-links", "summary": "Create a branded link", "tags": [ "Link branding" ], "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": "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 } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$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": [] } ] }, "get": { "operationId": "GET_whitelabel-links", "summary": "Retrieve all branded links", "tags": [ "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": "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_branding_200_response" } }, "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": [] } ] } }, "/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": [ "Link branding" ], "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": { "description": "", "schema": { "type": "object", "properties": { "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": { "message": { "type": "string", "description": "The reason why the link whitelabel could not be validated." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "examples": { "application/json": { "errors": [ { "message": "internal error getting CNAME" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/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": [ "Link branding" ], "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": { "$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": [] } ] } }, "/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_whitelabel-links-id", "summary": "Retrieve a branded link", "tags": [ "Link branding" ], "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": { "$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": [] } ] }, "patch": { "operationId": "PATCH_whitelabel-links-id", "summary": "Update a branded link", "tags": [ "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", "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": { "$ref": "#/definitions/link_branding_200_response" }, "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 branded link", "tags": [ "Link branding" ], "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 \"Retrieve a branded link\" 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": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links/default": { "get": { "operationId": "GET_whitelabel-links-default", "summary": "Retrieve the default branded link", "tags": [ "Link branding" ], "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 the \"Create a branded link\" endpoint or by calling the \"Update a branded link\" endpoint 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": { "$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": [] } ] } }, "/whitelabel/links/subuser": { "get": { "operationId": "GET_whitelabel-links-subuser", "summary": "Retrieve a subuser's branded link", "tags": [ "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": "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/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": [] } ] }, "delete": { "operationId": "DELETE_whitelabel-links-subuser", "summary": "Disassociate a branded link from a subuser", "tags": [ "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": "username", "in": "query", "description": "The username of the subuser account that you want to disassociate a branded link from.", "required": true, "type": "string" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/ips/warmup": { "post": { "operationId": "POST_ips-warmup", "summary": "Start warming up an IP address", "tags": [ "IP Warmup" ], "description": "**This endpoint allows you to put an IP address into warmup mode.**", "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" } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip_warmup_response" }, "examples": { "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": [] } ] }, "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/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 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.**\n\nYou can retrieve all of your warming IPs using the \"Retrieve all IPs currently in warmup\" endpoint.", "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip_warmup_response" }, "examples": { "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 warmup status could not be retrieved." } } } } } }, "examples": { "application/json": { "errors": [ { "field": null, "message": "resource not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_ips-warmup-ip_address", "summary": "Stop warming up an IP address", "tags": [ "IP Warmup" ], "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 \"Retrieve the warmpup status for a specific IP address\" endpoint.", "responses": { "204": { "description": "", "schema": { "type": "object" } }, "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 be removed from warmup." } } } } } }, "examples": { "application/json": { "errors": [ { "field": null, "message": "resource not found" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/ips": { "post": { "operationId": "POST_whitelabel-ips", "summary": "Set up reverse DNS", "tags": [ "Reverse DNS" ], "description": "**This endpoint allows you to set up reverse DNS.**", "parameters": [ { "name": "body", "in": "body", "schema": { "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" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/reverse_dns" }, "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": [] } ] }, "get": { "operationId": "GET_whitelabel-ips", "summary": "Retrieve all reverse DNS records", "tags": [ "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": "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 }, { "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": [] } ] } }, "/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 \"Retrieve all reverse DNS records\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "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": 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", "description": "A message describing why the reverse DNS could not be validated." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "examples": { "application/json": { "errors": [ { "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": "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.**\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"Retrieve all reverse DNS records\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/reverse_dns" }, "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" } } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_whitelabel-ips-id", "summary": "Delete a reverse DNS record", "tags": [ "Reverse DNS" ], "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 \"Retrieve all reverse DNS records\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "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", "in": "body", "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address that you want to validate." }, "source": { "type": "string", "description": "A one-word classifier for where this validation originated." } }, "required": [ "email" ], "example": { "email": "example@example.com", "source": "signup" } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "object", "required": [ "email", "verdict", "score", "local", "host", "checks", "ip_address" ], "properties": { "email": { "type": "string", "description": "The email being validated", "format": "email" }, "verdict": { "type": "string", "description": "A generic classification of whether or not the email address is valid.", "enum": [ "Valid", "Risky", "Invalid" ] }, "score": { "type": "number", "description": "A numeric representation of the email validity." }, "local": { "type": "string", "description": "The local part of the email address." }, "host": { "type": "string", "description": "The domain of the email address.", "format": "hostname" }, "suggestion": { "type": "string", "description": "A suggested correction in the event of domain name typos (e.g., gmial.com)" }, "checks": { "type": "object", "description": "Granular checks for email address validity.", "required": [ "domain", "local_part", "additional" ], "properties": { "domain": { "type": "object", "description": "Checks on the domain portion of the email address.", "required": [ "has_valid_address_syntax", "has_mx_or_a_record", "is_suspected_disposable_address" ], "properties": { "has_valid_address_syntax": { "type": "boolean", "description": "Whether the email address syntax is valid." }, "has_mx_or_a_record": { "type": "boolean", "description": "Whether the email has appropriate DNS records to deliver a message. " }, "is_suspected_disposable_address": { "type": "boolean", "description": "Whether the domain appears to be from a disposable email address service." } } }, "local_part": { "type": "object", "description": "Checks on the local part of the email address.", "required": [ "is_suspected_role_address" ], "properties": { "is_suspected_role_address": { "type": "boolean", "description": "Whether the local part of email appears to be a role or group (e.g., hr, admin)" } } }, "additional": { "type": "object", "description": "Additional checks on the email address.", "required": [ "has_known_bounces", "has_suspected_bounces" ], "properties": { "has_known_bounces": { "type": "boolean", "description": "WHether email sent to this address from your account has bounced." }, "has_suspected_bounces": { "type": "boolean", "description": "Whether our model predicts that the email address might bounce." } } } } }, "source": { "type": "string", "description": "The source of the validation, as per the API request." }, "ip_address": { "type": "string", "description": "The IP address associated with this email." } } } }, "required": [ "result" ] }, "examples": { "application/json": { "result": { "email": "cedric@fogowl.com", "verdict": "Valid", "score": 0.85021, "local": "cedric", "host": "fogowl.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": false } }, "ip_address": "192.168.1.1" } } } } }, "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 \"List all authenticated domains\" endpoint. You can retrieve all of your link IDs using the \"Retrieve all branded links\" 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": { "type": "object", "properties": { "error": { "type": "string" }, "field": { "type": "string" } } } } } } }, "security": [ { "Authorization": [] } ] } }, "/ips/pools": { "post": { "operationId": "POST_ips-pools", "summary": "Create an IP pool", "tags": [ "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": [ { "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/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 \"Retrieve all IP addresses\" endpoint.", "parameters": [ { "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": { "201": { "description": "", "schema": { "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" } }, "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": { "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": [ { "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": { "description": "The IP addresses that belong to this pool.", "type": "array", "items": { "type": "string" } } } }, "examples": { "application/json": { "pool_name": "Sample", "ips": [ "192.168.1.1", "192.158.1.2", "192.138.2.1" ] } } }, "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." } } } } } }, "examples": { "application/json": { "errors": [ { "field": "error", "message": "Unable to locate specified IPs Pool" } ] } } } }, "security": [ { "Authorization": [] } ] }, "put": { "operationId": "PUT_ips-pools-pool_name", "summary": "Rename an IP pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to update the name of an IP pool.**", "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" } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip_pool_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." } } } } } }, "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.**", "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/{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": [ "IP Pools" ], "description": "**This endpoint allows you to remove an IP address from an IP pool.**", "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": { "post": { "operationId": "POST_ips", "summary": "Add IPs", "tags": [ "IP Addresses" ], "description": "**This endpoint is for adding a(n) IP Address(es) to your account.**", "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" ] }, "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/global_error_response_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": [ "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": "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": { "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": [ { "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": [] } ] } }, "/ips/remaining": { "get": { "operationId": "GET_ips-remaining", "summary": "Get remaining IPs count", "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.**", "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" ] }, "examples": { "application/json": { "results": [ { "remaining": 2, "period": "month", "price_per_ip": 20 } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/ips/assigned": { "get": { "operationId": "GET_ips-assigned", "summary": "Retrieve all assigned IPs", "tags": [ "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": { "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 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": { "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": { "ip": "000.00.00.0", "subusers": [ "subuser1", "subuser2" ], "rdns": "o1.em.example.com", "pools": [ "test1" ], "warmup": false, "start_date": null, "whitelabeled": true } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains": { "get": { "operationId": "GET_whitelabel-domains", "summary": "List all authenticated domains", "tags": [ "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/domain-authentication-200-response" }, "examples": { "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": [] } ] }, "post": { "operationId": "POST_whitelabel-domains", "summary": "Authenticate a domain", "tags": [ "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": { "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": { "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/authentication::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, "type": "string" } ], "get": { "operationId": "GET_whitelabel-domains-domain_id", "summary": "Retrieve an authenticated domain", "tags": [ "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/authentication::domain" }, "examples": { "application/json": { "id": 45373692, "user_id": 66036447, "subdomain": "sub", "domain": "example.com", "username": "jdoe", "ips": [ "127.0.0.1" ], "custom_spf": false, "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": [] } ] }, "patch": { "operationId": "PATCH_whitelabel-domains-domain_id", "summary": "Update an authenticated domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to update the settings for an authenticated domain.**", "parameters": [ { "name": "body", "in": "body", "schema": { "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": { "default": false, "custom_spf": true } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain-authentication-200-response" }, "examples": { "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" } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/default": { "get": { "operationId": "GET_whitelabel-domains-default", "summary": "Get the default authentication", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve the default authentication for a domain.**\n\nWhen creating or updating a domain authentication, you can set the domain as a default. The default domain will be used to send all mail. If you have multiple authenticated domains, the authenticated domain matching the domain of the From address will be used, and the default will be overridden.\n\nThis endpoint will return a default domain and its details only if a default is set. You are not required to set a default. If you do not set a default domain, this endpoint will return general information about your domain authentication status.", "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": { "$ref": "#/definitions/domain-authentication-200-response" }, "examples": { "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": [] } ] } }, "/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": [ "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": { "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/domain_authentication: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", "description": "ID of the domain to delete the IP from.", "required": true, "type": "integer" }, { "name": "ip", "in": "path", "description": "IP to remove from the domain.", "required": true, "type": "string" } ], "delete": { "operationId": "DELETE_whitelabel-domains-id-ips-ip", "summary": "Remove an IP from an authenticated domain.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to remove an IP address from that domain's authentication.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain_authentication: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", "description": "ID of the domain to validate.", "required": true, "type": "integer" } ], "post": { "operationId": "POST_whitelabel-domains-id-validate", "summary": "Validate a domain authentication.", "tags": [ "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": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the authenticated domain." }, "valid": { "type": "boolean", "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", "null" ], "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": [ "string", "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": [ "string", "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": [ "string", "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": { "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 authenticated domain associated with the given user.", "tags": [ "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 an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domain.", "required": true, "type": "string" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain_authentication: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 an authenticated domain from a given user.", "tags": [ "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 an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domain.", "type": "string" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/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 an authenticated domain with a given user.", "tags": [ "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 an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Username to associate with the authenticated domain." } }, "required": [ "username" ], "example": { "username": "jdoe" } } } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/domain_authentication: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": [] } ] } }, "/verified_senders/domains": { "get": { "operationId": "GET_verified_senders-domains", "summary": "Domain Warn List", "tags": [ "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": { "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": { "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": [] } ] } }, "/verified_senders/steps_completed": { "get": { "operationId": "GET_verified_senders-steps_completed", "summary": "Completed Steps", "tags": [ "Sender Verification" ], "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 \"Authenticate a domain\" endpoint.", "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "results": { "type": "object", "properties": { "sender_verified": { "type": "boolean" }, "domain_verified": { "type": "boolean" } } } } }, "examples": { "application/json": { "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": [] } ] } }, "/verified_senders": { "post": { "operationId": "POST_verified_senders", "summary": "Create Verified Sender Request", "tags": [ "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": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/verified-sender-request-schema" } } ], "responses": { "201": { "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": { "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": [] } ] }, "get": { "operationId": "GET_verified_senders", "summary": "Get All Verified Senders", "tags": [ "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": "limit", "in": "query", "type": "number" }, { "name": "lastSeenID", "in": "query", "type": "number" }, { "name": "id", "in": "query", "type": "integer" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/verified-sender-response-schema" } } } }, "examples": { "application/json": { "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": [] } ] } }, "/verified_senders/verify/{token}": { "parameters": [ { "name": "token", "in": "path", "required": true, "type": "string" } ], "get": { "operationId": "GET_verified_senders-verify-token", "summary": "Verify Sender Request", "tags": [ "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": { "204": { "description": "" }, "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": [] } ] } }, "/verified_senders/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ], "patch": { "operationId": "PATCH_verified_senders-id", "summary": "Edit Verified Sender", "tags": [ "Sender Verification" ], "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/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": { "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": { "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": [] } ] }, "delete": { "operationId": "DELETE_verified_senders-id", "summary": "Delete Verified Sender", "tags": [ "Sender Verification" ], "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 \"Get All Verified Senders\" endpoint.", "responses": { "204": { "description": "", "schema": { "type": "object" } }, "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" ] } } } } }, "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": [] } ] } }, "/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": [ "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 \"Get All Verified Senders\" endpoint.", "responses": { "204": { "description": "", "schema": { "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": [ "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": [] } ] } }, "/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": [ "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/design-duplicate-input", "example": { "name": "Ahoy, Cake or Pie Cafe!", "editor": "design" } } } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/design-output" }, "examples": { "application/json": { "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 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 Valid operators for create and update depend on the type of the field for which you are searching.\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 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": { "$ref": "#/definitions/contactdb_custom_field_with_id" }, "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/global_error_response_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": "**This endpoint allows you to create a new segment.**\n\n\n Valid operators for create and update depend on the type of the field for which you are searching.\n\n**Dates**\n- \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n - You may use MM/DD/YYYY for day granularity or an epoch for second granularity.\n- \"empty\", \"not_empty\"\n- \"is within\"\n - You may use an [ISO 8601 date format](https://en.wikipedia.org/wiki/ISO_8601) or the # of days.\n\n**Text**\n- \"contains\"\n- \"eq\" (is/equals - matches the full field)\n- \"ne\" (is not/not equals - matches any field where the entire field is not the condition value)\n- \"empty\"\n- \"not_empty\"\n\n**Numbers**\n- \"eq\" (is/equals)\n- \"lt\" (is less than)\n- \"gt\" (is greater than)\n- \"empty\"\n- \"not_empty\"\n\n**Email Clicks and Opens**\n- \"eq\" (opened)\n- \"ne\" (not opened)\n\nAll field values must be a string.\n\n\nConditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either `clicks.campaign_identifier` or `opens.campaign_identifier`.\nThe condition value should be a string containing the id of a completed campaign.\n\n\nThe conditions list may contain multiple conditions, joined by an \"and\" or \"or\" in the \"and_or\" field.\n\nThe 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\"\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.**", "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", "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.", "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.", "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": "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\nIn 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.**", "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.**", "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": "**This endpoint allows you to update a specific campaign.**\n\nThis 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 an existing campaign.**\n\nNormally a POST request would have a 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 a 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": "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": [] } ] } }, "/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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "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 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": [ { "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.**\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": "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": [ { "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.**\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": [ { "$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": "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": [ { "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.**\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": "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": { "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_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": [] } ] } }, "/browsers/stats": { "get": { "operationId": "GET_browsers-stats", "summary": "Retrieve email statistics by browser.", "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 [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { "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": "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": [ { "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": [] } ] } }, "/suppression/bounces": { "get": { "operationId": "GET_suppression-bounces", "summary": "Retrieve all bounces", "tags": [ "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": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/bounce_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<% 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 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", "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" }, "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/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" } }, "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." } }, "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", "description": "The CNAME for your sending domain that points to sendgrid.net.", "required": [ "valid", "type", "host", "data" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this is a valid CNAME." }, "type": { "type": "string", "description": "The type of DNS record." }, "host": { "type": "string", "description": "The domain that this CNAME is created for.", "format": "hostname" }, "data": { "type": "string", "description": "The CNAME record." } } }, "dkim1": { "type": "object", "description": "A DNS record.", "required": [ "valid", "type", "host", "data" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this is a valid DNS record." }, "type": { "type": "string", "description": "The type of DNS record." }, "host": { "type": "string", "description": "The domain that this DNS record was created for." }, "data": { "type": "string", "description": "The DNS record." } } }, "dkim2": { "type": "object", "description": "A DNS record.", "required": [ "valid", "type", "host", "data" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this is a valid DNS record." }, "type": { "type": "string", "description": "The type of DNS record." }, "host": { "type": "string", "description": "The domain that this DNS record was created for." }, "data": { "type": "string", "description": "The DNS record." } } } } } }, "required": [ "id", "user_id", "subdomain", "domain", "username", "ips", "custom_spf", "default", "legacy", "automatic_security", "valid", "dns" ], "example": { "id": 45373692, "user_id": 66036447, "subdomain": "sub", "domain": "example.com", "username": "jdoe", "ips": [ "127.0.0.1" ], "custom_spf": false, "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" } } } }, "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 ] }, "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": "\n
| \n