-
-
- Validated link whitelabels marked as "default" -
- Legacy link whitelabels (migrated from the whitelabel wizard) -
- Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net) -
<% body %>Example
\n" - } - queryParameters: {} - patch: - displayName: Update template mail settings - description: |- - **This endpoint allows you to update your current legacy email template settings.** - - This setting refers to our original email templates. We currently support more fully featured [transactional templates](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). - - The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "enabled": true, - "html_content": "<% body %>" - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you want to enable the legacy email template mail setting." - }, - "html_content": { - "type": "string", - "description": "The new HTML content for your legacy email template." - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean" - }, - "html_content": { - "type": "string" - } - } - } - example: |- - { - "enabled": false, - "html_content": "<% body %>Example
\n" - } - queryParameters: {} - /address_whitelist: - displayName: address_whitelist - description: '' - uriParameters: {} - get: - displayName: Retrieve address whitelist mail settings - description: |- - **This endpoint allows you to retrieve your current email address whitelist settings.** - - The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_address_whitelabel" - } - example: |- - { - "enabled": false, - "list": [ - "example.com" - ] - } - queryParameters: {} - patch: - displayName: Update address whitelist mail settings - description: |- - **This endpoint allows you to update your current email address whitelist settings.** - - The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "enabled": true, - "list": [ - "email1@example.com", - "example.com" - ] - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if your email address whitelist is enabled." - }, - "list": { - "type": "array", - "description": "Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.", - "items": { - "type": "string" - } - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_address_whitelabel" - } - example: |- - { - "enabled": true, - "list": [ - "email1@example.com" - ] - } - queryParameters: {} - /footer: - displayName: footer - description: '' - uriParameters: {} - get: - displayName: Retrieve footer mail settings - description: |- - **This endpoint allows you to retrieve your current Footer mail settings.** - - The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_footer" - } - example: |- - { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - } - queryParameters: {} - patch: - displayName: Update footer mail settings - description: |- - **This endpoint allows you to update your current Footer mail settings.** - - The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "enabled": true, - "html_content": "...", - "plain_content": "..." - } - schema: |- - { - "$ref": "#/definitions/mail_settings_footer" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_footer" - } - example: |- - { - "enabled": true, - "html_content": "Example HTML content", - "plain_content": "Example plain content" - } - queryParameters: {} - /forward_spam: - displayName: forward_spam - description: '' - uriParameters: {} - patch: - displayName: Update forward spam mail settings - description: |- - **This endpoint allows you to update your current Forward Spam mail settings.** - - Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "email": "", - "enabled": false - } - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_spam" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_spam" - } - example: |- - { - "email": "", - "enabled": false - } - queryParameters: {} - get: - displayName: Retrieve forward spam mail settings - description: |- - **This endpoint allows you to retrieve your current Forward Spam mail settings.** - - Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_spam" - } - example: |- - { - "email": "", - "enabled": true - } - queryParameters: {} - /forward_bounce: - displayName: forward_bounce - description: '' - uriParameters: {} - patch: - displayName: Update forward bounce mail settings - description: |- - **This endpoint allows you to update your current bounce forwarding mail settings.** - - Activating this setting allows you to specify an email address to which bounce reports are forwarded. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "enabled": true, - "email": "example@example.com" - } - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_bounce" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_bounce" - } - example: |- - { - "email": "", - "enabled": true - } - queryParameters: {} - get: - displayName: Retrieve forward bounce mail settings - description: |- - **This endpoint allows you to retrieve your current bounce forwarding mail settings.** - - Activating this setting allows you to specify an email address to which bounce reports are forwarded. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_forward_bounce" - } - example: |- - { - "enabled": false, - "email": null - } - queryParameters: {} - /spam_check: - displayName: spam_check - description: '' - uriParameters: {} - get: - displayName: Retrieve spam check mail settings - description: |- - **This endpoint allows you to retrieve your current Spam Checker mail settings.** - - The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_spam_check" - } - example: |- - { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } - queryParameters: {} - patch: - displayName: Update spam check mail settings - description: |- - **This endpoint allows you to update your current spam checker mail settings.** - - The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "enabled": true, - "url": "url", - "max_score": 5 - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you want the spam check mail setting to be enabled or not." - }, - "url": { - "type": "string", - "description": "The Inbound Parse URL where you would like your spam reports to be sent to." - }, - "max_score": { - "type": "integer", - "default": 5, - "description": "The new max score, or spam threshold that you would like to set for the spam checker.", - "minimum": 1, - "maximum": 10 - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_spam_check" - } - example: |- - { - "enabled": false, - "max_score": 6, - "url": "http://example.com" - } - queryParameters: {} - /bcc: - displayName: bcc - description: '' - uriParameters: {} - get: - displayName: Retrieve all BCC mail settings - description: |- - **This endpoint allows you to retrieve your current BCC mail settings.** - - When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_bcc" - } - example: |- - { - "email": "example@example.com", - "enabled": false - } - queryParameters: {} - patch: - displayName: Update BCC mail settings - description: |- - **This endpoint allows you to update your current BCC mail settings.** - - When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "enabled": false, - "email": "email@example.com" - } - schema: |- - { - "$ref": "#/definitions/mail_settings_patch" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_patch" - } - example: |- - { - "email": "example@example.com", - "enabled": false - } - queryParameters: {} - /bounce_purge: - displayName: bounce_purge - description: '' - uriParameters: {} - patch: - displayName: Update bounce purge mail settings - description: |- - **This endpoint allows you to update your current bounce purge settings.** - - This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - body: - application/json: - example: |- - { - "enabled": true, - "hard_bounces": 5, - "soft_bounces": 5 - } - schema: |- - { - "$ref": "#/definitions/mail_settings_bounce_purge" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_bounce_purge" - } - example: |- - { - "enabled": false, - "hard_bounces": null, - "soft_bounces": null - } - queryParameters: {} - get: - displayName: Retrieve bounce purge mail settings - description: |- - **This endpoint allows you to retrieve your current bounce purge settings.** - - This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_settings_bounce_purge" - } - example: |- - { - "enabled": false, - "soft_bounces": 1234, - "hard_bounces": null - } - queryParameters: {} - uriParameters: {} - get: - displayName: Retrieve all mail settings - description: |- - **This endpoint allows you to retrieve a list of all mail settings.** - - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "The list of all mail settings.", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the mail setting." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this mail setting is currently enabled." - }, - "name": { - "type": "string", - "description": "The name of the mail setting." - }, - "description": { - "type": "string", - "description": "A description of the mail setting." - } - }, - "required": [ - "title", - "enabled", - "name", - "description" - ] - } - } - }, - "required": [ - "result" - ] - } - example: |- - { - "result": [ - { - "title": "Address Whitelist", - "enabled": false, - "name": "address_whitelist", - "description": "Address / domains that should never have email suppressed." - }, - { - "title": "BCC", - "enabled": false, - "name": "bcc", - "description": "Automatically BCC an address for every e-mail sent." - }, - { - "title": "Bounce Purge", - "enabled": false, - "name": "bounce_purge", - "description": "Allows you to automatically purge bounce records from SendGrid after a specified number of days." - }, - { - "title": "Event Notification", - "enabled": true, - "name": "event_notify", - "description": "Controls notifications for events, such as bounces, clicks, and opens." - }, - { - "title": "Footer", - "enabled": false, - "name": "footer", - "description": "Allows you to add a custom footer to outgoing email." - }, - { - "title": "Forward Bounce", - "enabled": true, - "name": "forward_bounce", - "description": "Allows you to forward bounces to a specific email address." - }, - { - "title": "Forward Spam", - "enabled": false, - "name": "forward_spam", - "description": "Allows for a copy of spam reports to be forwarded to an email address." - }, - { - "title": "Legacy Email Template", - "enabled": true, - "name": "template", - "description": "Allows you to customize your outgoing HTML emails." - }, - { - "title": "Plain Content", - "enabled": false, - "name": "plain_content", - "description": "Convert your plain text emails to HTML." - }, - { - "title": "Spam Checker", - "enabled": true, - "name": "spam_check", - "description": "Check outbound messages for spam content." - } - ] - } - queryParameters: - limit: - type: integer - description: The number of settings to return. - offset: - type: integer - description: Where in the list of results to begin displaying settings. -/campaigns: - displayName: campaigns - description: '' - '/{campaign_id}': - displayName: '{campaign_id}' - description: '' - /schedules: - displayName: schedules - description: '' - uriParameters: {} - get: - displayName: View Scheduled Time of a Campaign - description: |- - **This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.** - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "View Scheduled Time of a Campaign response", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": [ - "send_at" - ] - } - example: |- - { - "send_at": 1490778528 - } - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - patch: - displayName: Update a Scheduled Campaign - description: |- - **This endpoint allows to you change the scheduled time and date for a campaign to be sent.** - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: '' - schema: |- - { - "title": "Update a Scheduled Campaign request", - "type": "object", - "properties": { - "send_at": { - "type": "integer", - "format": "int64" - } - }, - "required": [ - "send_at" - ] - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "title": "Update a Scheduled Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID" - }, - "send_at": { - "type": "integer", - "description": "The unix timestamp to send the campaign." - }, - "status": { - "type": "string", - "description": "The status of the schedule." - } - }, - "required": [ - "id", - "send_at", - "status" - ] - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" - } - ] - } - description: |- - "": "The JSON you have submitted cannot be parsed." - "send_at": "Please choose a future time for sending your campaign." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - '403': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "send_at", - "message": "You cannot update the send_at value of non-scheduled campaign." - } - ] - } - description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - /test: - displayName: test - description: '' - uriParameters: {} - post: - displayName: Send a Test Campaign - description: |- - **This endpoint allows you to send a test campaign.** - - To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: |- - { - "to": "your.email@example.com" - } - schema: |- - { - "type": "object", - "properties": { - "to": { - "type": "string", - "description": "The email address that should receive the test campaign.", - "format": "email" - } - }, - "required": [ - "to" - ] - } - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "title": "Send a Test Campaign request", - "type": "object", - "properties": { - "to": { - "type": "string" - } - }, - "required": [ - "to" - ] - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "send_at", - "message": "Please choose a future time for sending your campaign." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - description: |- - "": "The JSON you have submitted cannot be parsed." - "to": "Please provide an email address to which the test should be sent." - "to": "You can only send tests to 10 addresses at a time." - "subject": "Please add a subject to your campaign before sending a test." - "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." - "sender_id": "Please assign a sender identity to your campaign before sending a test." - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - delete: - displayName: Unschedule a Scheduled Campaign - description: |- - **This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.** - - A successful unschedule will return a 204. - If the specified campaign is in the process of being sent, the only option is to cancel (a different method). - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '403': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "This campaign is already In Progress." - }, - { - "field": null, - "message": "This campaign is already Sent." - }, - { - "field": null, - "message": "This campaign is already Paused." - }, - { - "field": null, - "message": "This campaign is already Canceled." - } - ] - } - description: |- - "": "This campaign is already In Progress." - "": "This campaign is already Sent." - "": "This campaign is already Paused." - "": "This campaign is already Canceled." - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - /now: - displayName: now - description: '' - uriParameters: {} - post: - displayName: Send a Campaign - description: |- - **This endpoint allows you to immediately send a campaign at the time you make the API call.** - - Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: {} - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "title": "Send a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "format": "int64" - }, - "status": { - "type": "string" - } - }, - "required": [ - "id", - "status" - ] - } - example: |- - { - "id": 1234, - "status": "Scheduled" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '403': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "You may only send a campaign when it is in draft mode." - } - ] - } - description: '"": "You may only send a campaign when it is in draft mode."' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - post: - displayName: Schedule a Campaign - description: |- - **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: |- - { - "send_at": 1489771528 - } - 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" - ] - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "title": "Schedule a Campaign response", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The campaign ID." - }, - "send_at": { - "type": "integer", - "description": "The date time you scheduled your campaign to be sent." - }, - "status": { - "type": "string", - "description": "The status of your campaign.", - "enum": [ - "Scheduled" - ] - } - }, - "required": [ - "id", - "send_at", - "status" - ] - } - example: |- - { - "id": 1234, - "send_at": 1489771528, - "status": "Scheduled" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "subject", - "message": "subject can't be blank" - }, - { - "field": "sender_id", - "message": "sender_id can't be blank" - }, - { - "field": "plain_content", - "message": "plain_content can't be blank, please provide plain text or html content" - }, - { - "field": "list_id", - "message": "You must select at least 1 segment or 1 list to send to." - }, - { - "field": "unsubscribe_tag", - "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - }, - { - "field": "suppression_group_id", - "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - }, - { - "field": null, - "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - } - ] - } - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "send_at": "Please choose a future time for sending your campaign." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "The JSON you have submitted cannot be parsed." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '403': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH." - } - ] - } - description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - uriParameters: - campaign_id: - type: integer - description: The ID of the campaign that you would like to update. - displayName: The ID of the campaign that you would like to update. - delete: - displayName: Delete a Campaign - description: |- - **This endpoint allows you to delete a specific campaign.** - - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "null" - } - example: '' - '401': - body: - application/json: - schema: |- - { - "type": "object" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - description: '"": "not found"' - queryParameters: {} - get: - displayName: Retrieve a single campaign - description: |- - **This endpoint allows you to retrieve a specific campaign.** - - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/campaign_response" - } - example: |- - { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "Check out our spring line!
", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - '401': - body: - application/json: - schema: |- - { - "type": "object" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '404': - body: - application/json: - schema: |- - { - "type": "object" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - patch: - displayName: Update a Campaign - description: |- - Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: |- - { - "title": "May Newsletter", - "subject": "New Products for Summer!", - "categories": [ - "summer line" - ], - "html_content": "Check out our summer line!
", - "plain_content": "Check out our summer line!" - } - schema: |- - { - "title": "Update a Campaign request", - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The title of the campaign." - }, - "subject": { - "type": "string", - "description": "The subject line for your campaign." - }, - "categories": { - "type": "array", - "description": "The categories you want to tag on this campaign.", - "items": { - "type": "string" - } - }, - "html_content": { - "type": "string", - "description": "The HTML content of this campaign." - }, - "plain_content": { - "type": "string", - "description": "The plain content of this campaign." - } - }, - "required": [ - "title", - "subject", - "categories", - "html_content", - "plain_content" - ] - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/campaign_response" - } - 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" - } - '400': - body: - application/json: - schema: |- - { - "type": "object" - } - example: |- - { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" - }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" - }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" - }, - { - "field": "sender_id", - "message": "sender_id does not exist" - }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" - }, - { - "field": "list_ids", - "message": "list_ids do not all exist" - }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" - }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" - }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" - }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - } - ] - } - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - '403': - body: - application/json: - schema: |- - { - "type": "object" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "You may only update a campaign when it is in draft mode." - } - ] - } - description: '"": "You may only update a campaign when it is in draft mode."' - '404': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "not found" - } - ] - } - description: '"": "not found"' - queryParameters: {} - uriParameters: {} - get: - displayName: Retrieve all Campaigns - description: |- - **This endpoint allows you to retrieve a list of all of your campaigns.** - - Returns campaigns in reverse order they were created (newest first). - - Returns an empty array if no campaigns exist. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "$ref": "#/definitions/campaign_response" - } - } - } - } - example: |- - { - "result": [ - { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "Check out our spring line!
", - "plain_content": "Check out our spring line!", - "status": "Draft" - }, - { - "id": 986723, - "title": "February Newsletter", - "subject": "Final Winter Product Sale!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "winter line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "Last call for winter clothes!
", - "plain_content": "Last call for winter clothes!", - "status": "Sent" - } - ] - } - queryParameters: - limit: - type: number - description: The number of results you would like to receive at a time. - default: 10 - offset: - type: number - description: 'The index of the first campaign to return, where 0 is the first campaign.' - default: 0 - post: - displayName: Create a Campaign - description: |- - **This endpoint allows you to create a campaign.** - - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - - Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. - - For more information: - - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - body: - application/json: - example: |- - { - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "Check out our spring line!
", - "plain_content": "Check out our spring line!" - } - schema: |- - { - "$ref": "#/definitions/campaign_request" - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/campaign_response" - } - example: |- - { - "id": 986724, - "title": "March Newsletter", - "subject": "New Products for Spring!", - "sender_id": 124451, - "list_ids": [ - 110, - 124 - ], - "segment_ids": [ - 110 - ], - "categories": [ - "spring line" - ], - "suppression_group_id": 42, - "custom_unsubscribe_url": "", - "ip_pool": "marketing", - "html_content": "Check out our spring line!
", - "plain_content": "Check out our spring line!", - "status": "Draft" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": "title", - "message": "title can't be blank" - }, - { - "field": "title", - "message": "title is too long (maximum is 100 characters)" - }, - { - "field": "categories", - "message": "categories exceeds 10 category limit" - }, - { - "field": "html_content", - "message": "html_content exceeds the 1MB limit" - }, - { - "field": "plain_content", - "message": "plain_content exceeds the 1MB limit" - }, - { - "field": "sender_id", - "message": "sender_id does not exist" - }, - { - "field": "sender_id", - "message": "sender_id is not a verified sender identity" - }, - { - "field": "list_ids", - "message": "list_ids do not all exist" - }, - { - "field": "segment_ids", - "message": "segment_ids do not all exist" - }, - { - "field": "ip_pool", - "message": "The ip pool you provided is invalid" - }, - { - "field": "suppression_group_id", - "message": "suppression_group_id does not exist" - }, - { - "field": "unsubscribes", - "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - }, - { - "field": null, - "message": "The JSON you have submitted cannot be parsed." - }, - { - "field": null, - "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." - } - ] - } - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." - '401': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - queryParameters: {} -/partner_settings: - displayName: partner_settings - description: '' - /new_relic: - displayName: new_relic - description: '' - uriParameters: {} - patch: - displayName: Updates New Relic partner settings. - description: |- - **This endpoint allows you to update or change your New Relic partner settings.** - - Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). - - By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). - body: - application/json: - example: |- - { - "license_key": "", - "enabled": true, - "enable_subuser_statistics": true - } - 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." - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/partner_settings_new_relic" - } - example: |- - { - "enable_subuser_statistics": true, - "enabled": true, - "license_key": "" - } - queryParameters: {} - get: - displayName: Returns all New Relic partner settings. - description: |- - **This endpoint allows you to retrieve your current New Relic partner settings.** - - Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). - - By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/partner_settings_new_relic" - } - example: |- - { - "enable_subuser_statistics": false, - "enabled": true, - "license_key": "" - } - queryParameters: {} - uriParameters: {} - get: - displayName: Returns a list of all partner settings. - description: |- - **This endpoint allows you to retrieve a list of all partner settings that you can enable.** - - Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). - headers: {} - responses: - '200': - body: - application/json: - 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" - ] - } - } - } - } - example: |- - { - "result": [ - { - "title": "Partner title", - "enabled": true, - "name": "partner_name", - "description": "A description of a partner." - } - ] - } - queryParameters: - limit: - type: integer - description: The number of settings to return per page. - offset: - type: integer - description: The paging offset. -/mail: - displayName: mail - description: '' - /batch: - displayName: batch - description: '' - '/{batch_id}': - displayName: '{batch_id}' - description: '' - uriParameters: - batch_id: - type: string - get: - displayName: Validate batch ID - description: |- - **This endpoint allows you to validate a batch ID.** - - If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. - - More Information: - - * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_batch_id" - } - example: |- - { - "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" - } - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "invalid batch id" - } - ] - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - description: Unexpected error in API call. See HTTP response body for details. - queryParameters: {} - uriParameters: {} - post: - displayName: Create a batch ID - description: |- - **This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.** - - If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. - - More Information: - - * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) - body: {} - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/mail_batch_id" - } - example: |- - { - "batch_id": "YOUR_BATCH_ID" - } - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/global:ErrorResponse" - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} - /send: - displayName: send - description: '' - /beta: - displayName: beta - description: '' - uriParameters: {} - post: - displayName: v3 Mail Send Beta - description: |- - This endpoint allows you to send email over SendGrid’s v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our [v2 API Reference](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - * Top level parameters are referred to as "global". - * Individual fields within the personalizations array will override any other global, or “message level”, parameters that are defined outside of personalizations. - - For an overview of the v3 Mail Send endpoint, please visit our [v3 API Reference](https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html) - - For more detailed information about how to use the v3 Mail Send endpoint, please visit our [Classroom](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/index.html). - body: - application/json: - example: |- - { - "personalizations": [ - { - "to": [ - { - "email": "john.doe@example.com", - "name": "John Doe" - } - ], - "cc": [ - { - "email": "jane.doe@example.com", - "name": "Jane Doe" - } - ], - "bcc": [ - { - "email": "sam.doe@example.com", - "name": "Sam Doe" - } - ], - "subject": "Hello, World!", - "headers": { - "X-Accept-Language": "en", - "X-Mailer": "MyApp" - }, - "substitutions": { - "sub": { - "%name%": [ - "John", - "Jane", - "Sam" - ] - } - }, - "custom_args": { - "customerAccountNumber": "[CUSTOMER ACCOUNT NUMBER GOES HERE]", - "activationAttempt": "1", - "New Argument 1": "New Value 1" - }, - "send_at": 1409348513 - } - ], - "from": { - "email": "sam.smith@example.com", - "name": "Sam Smith" - }, - "reply_to": { - "email": "sam.smith@example.com", - "name": "Sam Smith" - }, - "subject": "Hello, World!", - "content": [ - { - "type": "text/html", - "value": "Hello, world!
ThanksThe SendGrid Team
" - }, - "sandbox_mode": { - "enable": false - }, - "spam_check": { - "enable": true, - "threshold": 3, - "post_to_url": "http://example.com/compliance" - } - }, - "tracking_settings": { - "click_tracking": { - "enable": true, - "enable_text": true - }, - "open_tracking": { - "enable": true, - "substitution_tag": "%opentrack" - }, - "subscription_tracking": { - "enable": true, - "text": "If you would like to unsubscribe and stop receiveing these emails <% click here %>.", - "html": "If you would like to unsubscribe and stop receiving these emails <% clickhere %>.", - "substitution_tag": "<%click here%>" - }, - "ganalytics": { - "enable": true, - "utm_campaign": "[NAME OF YOUR REFERRER SOURCE]", - "utm_medium": "[NAME OF YOUR MARKETING MEDIUM e.g. email]", - "utm_term": "[IDENTIFY PAID KEYWORDS HERE]", - "utm_content": "[USE THIS SPACE TO DIFFERENTIATE YOUR EMAIL FROM ADS]", - "utm_name": "[NAME OF YOUR CAMPAIGN]" - } - } - } - 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.", - "uniqueItems": false, - "maxItems": 100, - "items": { - "type": "object", - "properties": { - "to": { - "type": "array", - "description": "An array of recipients. Each object within this array may contain the name, but must always contain the email, of a recipient.", - "minItems": 1, - "maxItems": 100, - "items": { - "type": "object", - "properties": { - "": { - "$ref": "#/definitions/email_object" - } - } - } - }, - "cc": { - "type": "array", - "description": "An array of recipients who will receive a copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.", - "maxItems": 100, - "items": { - "type": "object", - "properties": { - "": { - "$ref": "#/definitions/email_object" - } - } - } - }, - "bcc": { - "type": "array", - "description": "An array of recipients who will receive a blind carbon copy of your email. Each object within this array may contain the name, but must always contain the email, of a recipient.", - "maxItems": 100, - "items": { - "type": "object", - "properties": { - "": { - "$ref": "#/definitions/email_object" - } - } - } - }, - "subject": { - "type": "string", - "description": "The subject of your email. Char length requirements, according to the RFC - http://stackoverflow.com/questions/1592291/what-is-the-email-subject-length-limit#answer-1592310", - "minLength": 1 - }, - "headers": { - "type": "object", - "description": "A collection of JSON key/value pairs allowing you to specify specific handling instructions for your email. You may not overwrite the following headers: x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC" - }, - "substitutions": { - "type": "object", - "description": "A collection of key/value pairs following the pattern \"substitution_tag\":\"value to substitute\". All are assumed to be strings. These substitutions will apply to the text and html content of the body of your email, in addition to the `subject` and `reply-to` parameters.", - "maxProperties": 10000 - }, - "custom_args": { - "type": "object", - "description": "Values that are specific to this personalization that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. May not exceed 10,000 bytes." - }, - "send_at": { - "type": "integer", - "description": "A unix timestamp allowing you to specify when you want your email to be delivered. Scheduling more than 72 hours in advance is forbidden." - } - }, - "required": [ - "to" - ] - } - }, - "from": { - "type": "object", - "description": "An email object containing the email address and name of the sender.", - "properties": { - "": { - "$ref": "#/definitions/email_object" - } - } - }, - "reply_to": { - "type": "object", - "description": "An email object containing the email address and name of the individual who should receive responses to your email.", - "properties": { - "": { - "$ref": "#/definitions/email_object" - } - } - }, - "subject": { - "type": "string", - "description": "The global, or “message level”, subject of your email. This may be overridden by personalizations[x].subject.", - "minLength": 1 - }, - "content": { - "type": "array", - "description": "An array in which you may specify the content of your email. You can include multiple mime types of content, but you must specify at least one mime type. To include more than one mime type, simply add another object to the array containing the `type` and `value` parameters.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The mime type of the content you are including in your email. For example, “text/plain” or “text/html”.", - "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 in which 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. For example, “text/plain” or “text/html”.", - "minLength": 1 - }, - "filename": { - "type": "string", - "description": "The filename of the attachment." - }, - "disposition": { - "type": "string", - "default": "inline, attachment", - "description": "The content-disposition of the attachment specifying how you would like the attachment to be displayed. For example, “inline” results in the attached file being displayed automatically within the message while “attachment” results in the attached file requiring some action to be taken before it is displayed (e.g. opening or downloading the file).", - "enum": [ - "inline", - "attachment" - ] - }, - "content_id": { - "type": "string", - "description": "The content id for the attachment. This is used when the disposition is set to “inline” and the attachment is an image, allowing the file to be displayed within the body of your email." - } - }, - "required": [ - "content", - "filename" - ] - } - }, - "template_id": { - "type": "string", - "description": "The id of a template that you would like to use. If you use a template that contains a subject and content (either text or html), you do not need to specify those at the personalizations nor message level. " - }, - "sections": { - "type": "object", - "description": "An object of key/value pairs that define block sections of code to be used as substitutions." - }, - "headers": { - "type": "object", - "description": "An object containing key/value pairs of header names and the value to substitute for them. You must ensure these are properly encoded if they contain unicode characters. Must not be one of the reserved headers." - }, - "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": { - "type": "object", - "description": "Values that are specific to the entire send that will be carried along with the email and its activity data. Substitutions will not be made on custom arguments, so any string that is entered into this parameter will be assumed to be the custom argument that you would like to be used. This parameter is overridden by personalizations[x].custom_args if that parameter has been defined. Total custom args size may not exceed 10,000 bytes." - }, - "send_at": { - "type": "integer", - "description": "A unix timestamp allowing you to specify when you want your email to be delivered. This may be overridden by the personalizations[x].send_at parameter. Scheduling more ta 72 hours in advance is forbidden." - }, - "batch_id": { - "type": "string", - "description": "This ID represents a batch of emails to be sent at the same time. Including a batch_id in your request allows you include this email in that batch, and also enables you to cancel or pause the delivery of that batch. For more information, see https://sendgrid.com/docs/API_Reference/Web_API_v3/cancel_schedule_send.html " - }, - "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": { - "bcc": { - "type": "object", - "description": "This allows you to have a blind carbon copy automatically sent to the specified email address for every email that is sent.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - }, - "email": { - "type": "string", - "description": "The email address that you would like to receive the BCC.", - "format": "email" - } - } - }, - "bypass_list_management": { - "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.", - "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": "This 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." - } - } - }, - "spam_check": { - "type": "object", - "description": "This allows you to test the content of your email for spam.", - "properties": { - "enable": { - "type": "boolean", - "description": "Indicates if this setting is enabled." - }, - "threshold": { - "type": "integer", - "description": "The threshold used to determine if your content qualifies as spam on a scale from 1 to 10, with 10 being most strict, or most likely to be considered as spam.", - "minimum": 1, - "maximum": 10 - }, - "post_to_url": { - "type": "string", - "description": "An Inbound Parse URL that you would like a copy of your email along with the spam report to be sent to." - } - } - } - } - }, - "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 whether 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 whether the email was opened or not, but including a single pixel image in the body of the content. When the pixel is loaded, we can log that the email was opened.", - "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.\t" - }, - "utm_content": { - "type": "string", - "description": "Used to differentiate your campaign from advertisements.\t" - }, - "utm_campaign": { - "type": "string", - "description": "The name of the campaign.\t" - } - } - } - } - } - }, - "required": [ - "personalizations", - "from", - "reply_to", - "subject", - "content" - ] - } - headers: {} - responses: - '202': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - '400': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/errors" - } - example: '' - '401': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/errors" - } - example: '' - '413': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/errors" - } - example: '' - queryParameters: {} -/ips: - displayName: ips - description: '' - /assigned: - displayName: assigned - description: '' - uriParameters: {} - get: - displayName: Retrieve all assigned IPs - description: |- - **This endpoint allows you to retrieve only assigned IP addresses.** - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - headers: {} - responses: - '200': - body: - application/json: - 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" - ] - } - } - example: |- - [ - { - "ip": "167.89.21.3", - "pools": [ - "new_test5" - ], - "warmup": true, - "start_date": 1409616000 - } - ] - queryParameters: {} - /pools: - displayName: pools - description: '' - uriParameters: {} - post: - displayName: Create an IP pool. - description: |- - **This endpoint allows you to create an IP pool.** - - **Each user can create up to 10 different IP pools.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - body: - application/json: - example: |- - { - "name": "marketing" - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of your new IP pool.", - "maxLength": 64 - } - }, - "required": [ - "name" - ] - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/ip_pool" - } - example: |- - { - "name": "marketing" - } - queryParameters: {} - get: - displayName: Retrieve all IP pools. - description: |- - **This endpoint allows you to retreive all of your IP pools.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/ip_pool" - } - } - example: |- - [ - { - "name": "marketing" - }, - { - "name": "transactional" - } - ] - queryParameters: {} - '/{pool_name}': - displayName: '{pool_name}' - description: '' - uriParameters: - pool_name: - type: string - description: The name of the IP pool that you want to rename. - maxLength: 64 - displayName: The name of the IP pool that you want to rename. - get: - displayName: Retrieve all IPs in a specified pool. - description: |- - **This endpoint allows you to list all of the IP addresses that are in a specific IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "pool_name": { - "type": "string", - "description": "The name of the IP pool.", - "maxLength": 64 - }, - "ips": { - "type": "array", - "description": "The list of IP addresses that belong to this IP pool.", - "items": { - "type": "string" - } - } - }, - "required": [ - "pool_name" - ] - } - example: '' - '404': - body: - application/json: - 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." - } - } - } - } - } - } - example: |- - { - "errors": [ - { - "field": "error", - "message": "Unable to locate specified IPs Pool" - } - ] - } - queryParameters: {} - delete: - displayName: Delete an IP pool. - description: |- - **This endpoint allows you to delete an IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - '404': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "error": { - "type": "string", - "description": "An error explaining why the pool could not be deleted." - } - } - } - example: |- - { - "error": "Unable to locate specified IPs Pool" - } - queryParameters: {} - put: - displayName: Update an IP pool’s name. - description: |- - **This endpoint allows you to update the name of an IP pool.** - - IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - - IP pools can only be used with whitelabeled IP addresses. - - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - body: - application/json: - example: |- - { - "name": "new_pool_name" - } - schema: |- - { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The new name for your IP pool.", - "maxLength": 64 - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/ip_pool" - } - example: |- - { - "name": "new_pool_name" - } - '404': - body: - application/json: - 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." - } - } - } - } - } - } - example: |- - { - "errors": [ - { - "field": null, - "message": "ip pool not found" - } - ] - } - queryParameters: {} - /ips: - displayName: ips - description: '' - uriParameters: {} - post: - displayName: Add an IP address to a pool - description: |- - **This endpoint allows you to add an IP address to an IP pool.** - - You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - body: - application/json: - example: |- - { - "ip": "0.0.0.0" - } - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address that you want to add to an IP pool." - } - } - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "pools": { - "type": "array", - "description": "The list of IP pools that this IP address has been added to.", - "items": { - "type": "string" - } - }, - "start_date": { - "type": "integer", - "description": "A unix timestamp indicating when the warmup process began for the IP address." - }, - "warmup": { - "type": "boolean", - "description": "Indicates if the IP address is in warmup." - } - }, - "required": [ - "ip", - "pools", - "start_date", - "warmup" - ] - } - example: |- - { - "ip": "000.00.00.0", - "pools": [ - "test1" - ], - "start_date": 1409616000, - "warmup": true - } - '404': - body: - application/json: - 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." - } - } - } - } - } - } - example: |- - { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - queryParameters: {} - '/{ip}': - displayName: '{ip}' - description: '' - uriParameters: - ip: - type: string - description: The IP address that you are removing. - displayName: The IP address that you are removing. - delete: - displayName: Remove an IP address from a pool. - description: |- - **This endpoint allows you to remove an IP address from an IP pool.** - - The same IP address can be added to multiple IP pools. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - '404': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "error": { - "type": "string", - "description": "An error explaining why the IP address could not be removed from the IP pool." - } - } - } - example: |- - { - "error": "Unable to locate specified IPs Pool" - } - queryParameters: {} - /warmup: - displayName: warmup - description: '' - uriParameters: {} - get: - displayName: Retrieve all IPs currently in warmup - description: |- - **This endpoint allows you to retrieve all of your IP addresses that are currently warming up.** - - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/ip_warmup_response" - } - example: |- - [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - queryParameters: {} - post: - displayName: Add an IP to warmup - description: |- - **This endpoint allows you to enter an IP address into warmup mode.** - - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - body: - application/json: - example: |- - { - "ip": "0.0.0.0" - } - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address that you want to begin warming up." - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/ip_warmup_response" - } - example: |- - [ - { - "ip": "0.0.0.0", - "start_date": 1409616000 - } - ] - '404': - body: - application/json: - 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." - } - } - } - } - } - } - example: |- - { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - queryParameters: {} - '/{ip_address}': - displayName: '{ip_address}' - description: '' - uriParameters: - ip_address: - type: string - description: The IP address that you want to retrieve the warmup status for. - displayName: The IP address that you want to retrieve the warmup status for. - delete: - displayName: Remove an IP from warmup - description: |- - **This endpoint allows you to remove an IP address from warmup mode.** - - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object" - } - example: '' - '404': - body: - application/json: - 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." - } - } - } - } - } - } - example: |- - { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - queryParameters: {} - get: - displayName: Retrieve warmup status for a specific IP address - description: |- - **This endpoint allows you to retrieve the warmup status for a specific IP address.** - - SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup. - - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/ip_warmup_response" - } - example: '' - '404': - body: - application/json: - 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." - } - } - } - } - } - } - example: |- - { - "errors": [ - { - "field": null, - "message": "resource not found" - } - ] - } - queryParameters: {} - uriParameters: {} - get: - displayName: Retrieve all IP addresses - description: |- - **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** - - Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "An IP address." - }, - "subusers": { - "type": "array", - "description": "The subusers that are able to send email from this IP.", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for this IP address." - }, - "pools": { - "type": "array", - "description": "The IP pools that this IP has been added to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "type": [ - "number", - "null" - ], - "description": "The date that the IP address was entered into warmup." - }, - "whitelabeled": { - "type": "boolean", - "description": "Indicates if this IP address has been whitelabeled." - } - }, - "required": [ - "ip", - "subusers", - "pools", - "warmup", - "start_date", - "whitelabeled" - ] - } - } - example: |- - [ - { - "ip": "127.0.0.1", - "subusers": [ - "example_subuser1", - "example_subuser2" - ], - "rdns": "o1.em.example.com", - "pools": [], - "warmup": true, - "start_date": 1250337600, - "whitelabeled": true - }, - { - "ip": "127.0.0.1", - "subusers": [], - "pools": [], - "warmup": false, - "start_date": null, - "whitelabeled": false - } - ] - queryParameters: - ip: - type: string - description: The IP address to get - exclude_whitelabels: - type: boolean - description: Should we exclude whitelabels? - subuser: - type: string - description: The subuser you are requesting for. - limit: - type: integer - description: The number of IPs you want returned at the same time. - default: 10 - offset: - type: integer - description: The offset for the number of IPs that you are requesting. - default: 0 - '/{ip_address}': - displayName: '{ip_address}' - description: '' - uriParameters: - ip_address: - type: string - description: The IP address you are retrieving the IP pools for. - displayName: The IP address you are retrieving the IP pools for. - get: - displayName: Retrieve all IP pools an IP address belongs to - description: |- - **This endpoint allows you to see which IP pools a particular IP address has been added to.** - - The same IP address can be added to multiple IP pools. - - A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "subusers": { - "type": "array", - "description": "The subusers that can send email using this IP address.", - "items": { - "type": "string" - } - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for this IP address." - }, - "pools": { - "type": "array", - "description": "The list of IP pools that this IP address belongs to.", - "items": { - "type": "string" - } - }, - "warmup": { - "type": "boolean", - "description": "Indicates if this IP address is currently warming up." - }, - "start_date": { - "type": [ - "integer", - "null" - ], - "description": "The date that the IP address was entered into warmup." - }, - "whitelabeled": { - "type": "boolean", - "description": "Indicates if this IP address has been whitelabeled." - } - }, - "required": [ - "ip", - "subusers", - "rdns", - "pools", - "warmup", - "start_date", - "whitelabeled" - ] - } - example: |- - { - "ip": "000.00.00.0", - "subusers": [ - "subuser1", - "subuser2" - ], - "rdns": "o1.em.example.com", - "pools": [ - "test1" - ], - "warmup": false, - "start_date": null, - "whitelabeled": true - } - queryParameters: {} -/tracking_settings: - displayName: tracking_settings - description: '' - /click: - displayName: click - description: '' - uriParameters: {} - get: - displayName: Retrieve Click Track Settings - description: |- - **This endpoint allows you to retrieve your current click tracking setting.** - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enable_text": { - "type": "boolean", - "description": "Indicates if click tracking is enabled for plain text emails." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if click tracking is enabled or disabled." - } - }, - "required": [ - "enable_text", - "enabled" - ] - } - example: |- - { - "enable_text": false, - "enabled": true - } - queryParameters: {} - patch: - displayName: Update Click Tracking Settings - description: |- - **This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - body: - application/json: - example: |- - { - "enabled": true - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "The setting you want to use for click tracking." - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enable_text": { - "type": "boolean", - "description": "Indicates if click tracking is enabled for plain text emails" - }, - "enabled": { - "type": "boolean", - "description": "The new setting new setting for click tracking." - } - }, - "required": [ - "enable_text", - "enabled" - ] - } - example: |- - { - "enable_text": false, - "enabled": true - } - queryParameters: {} - /subscription: - displayName: subscription - description: '' - uriParameters: {} - patch: - displayName: Update Subscription Tracking Settings - description: |- - **This endpoint allows you to update your current settings for subscription tracking.** - - Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - body: - application/json: - example: |- - { - "enabled": true, - "landing": "landing page html", - "url": "url", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" - } - schema: |- - { - "$ref": "#/definitions/subscription_tracking_settings" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/subscription_tracking_settings" - } - example: |- - { - "enabled": true, - "landing": "landing page html", - "url": "url", - "replace": "replacement tag", - "html_content": "html content", - "plain_content": "text content" - } - queryParameters: {} - get: - displayName: Retrieve Subscription Tracking Settings - description: |- - **This endpoint allows you to retrieve your current settings for subscription tracking.** - - Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/subscription_tracking_settings" - } - example: |- - { - "enabled": true, - "html_content": "Something something unsubscribe <% %> something something
\n", - "landing": "subscribehere
\n", - "plain_content": "Something something unsubscribe <% %> something something", - "replace": "thetag", - "url": "" - } - queryParameters: {} - uriParameters: {} - get: - displayName: Retrieve Tracking Settings - description: |- - **This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "The list of all tracking settings.", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the event being tracked." - }, - "title": { - "type": "string", - "description": "The title of the tracking setting." - }, - "description": { - "type": "string", - "description": "A description about the event that is being tracked." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this tracking setting is currently enabled." - } - } - } - } - } - } - example: |- - { - "result": [ - { - "name": "open", - "title": "Open Tracking", - "description": "lorem ipsum... .", - "enabled": true - } - ] - } - queryParameters: - limit: - type: integer - description: The number of settings to return. - offset: - type: integer - description: Where in the list of results you want to begin retrieving settings. - /google_analytics: - displayName: google_analytics - description: '' - uriParameters: {} - get: - displayName: Retrieve Google Analytics Settings - description: |- - **This endpoint allows you to retrieve your current setting for Google Analytics.** - - For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). - - We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/google_analytics_settings" - } - example: |- - { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" - } - queryParameters: {} - patch: - displayName: Update Google Analytics Settings - description: |- - **This endpoint allows you to update your current setting for Google Analytics.** - - For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). - - We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - body: - application/json: - example: |- - { - "enabled": true, - "utm_source": "sendgrid.com", - "utm_medium": "email", - "utm_term": "", - "utm_content": "", - "utm_campaign": "website" - } - schema: |- - { - "$ref": "#/definitions/google_analytics_settings" - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "$ref": "#/definitions/google_analytics_settings" - } - example: |- - { - "enabled": true, - "utm_campaign": "", - "utm_content": "lotsandlotsofcontent", - "utm_medium": "", - "utm_source": "", - "utm_term": "" - } - queryParameters: {} - /open: - displayName: open - description: '' - uriParameters: {} - get: - displayName: Get Open Tracking Settings - description: |- - **This endpoint allows you to retrieve your current settings for open tracking.** - - Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if open tracking is enabled." - } - }, - "required": [ - "enabled" - ] - } - example: |- - { - "enabled": true - } - queryParameters: {} - patch: - displayName: Update Open Tracking Settings - description: |- - **This endpoint allows you to update your current settings for open tracking.** - - Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrid’s server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. - - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - body: - application/json: - example: |- - { - "enabled": true - } - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "The new status that you want to set for open tracking." - } - } - } - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if open tracking is enabled." - } - }, - "required": [ - "enabled" - ] - } - example: |- - { - "enabled": true - } - queryParameters: {} -/clients: - displayName: clients - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve email statistics by client type. - description: |- - **This endpoint allows you to retrieve your email statistics segmented by client type.** - - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - } - example: |- - [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] - } - ] - queryParameters: - start_date: - type: string - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - end_date: - type: string - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. - aggregated_by: - type: string - description: 'How to group the statistics. Must be either "day", "week", or "month".' - enum: - - day - - week - - month - '/{client_type}': - displayName: '{client_type}' - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve stats by a specific client type. - description: |- - **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** - - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - - ## Available Client Types - - phone - - tablet - - webmail - - desktop - - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - } - example: |- - [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "opens": 1, - "unique_opens": 1 - }, - "name": "Gmail", - "type": "client" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "opens": 0, - "unique_opens": 0 - }, - "name": "Gmail", - "type": "client" - } - ] - } - ] - queryParameters: - start_date: - type: string - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - end_date: - type: string - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. - aggregated_by: - type: string - description: 'How to group the statistics. Must be either "day", "week", or "month".' - enum: - - day - - week - - month -/devices: - displayName: devices - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve email statistics by device type. - description: "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html)." - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_opens" - } - } - example: |- - [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "device", - "name": "Webmail", - "metrics": { - "opens": 0, - "unique_opens": 0 - } - } - ] - }, - { - "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 - } - } - ] - } - ] - queryParameters: - end_date: - type: string - description: The end date of the statistics to retrieve. Defaults to today. - limit: - type: integer - description: How many results to include on each page. - offset: - type: integer - description: How many results to exclude. - aggregated_by: - type: string - description: 'How to group the statistics. Must be either "day", "week", or "month".' - start_date: - type: string - description: The starting date of the statistics to retrieve. - required: true -/scopes: - displayName: scopes - description: '' - uriParameters: {} - get: - displayName: Retrieve a list of scopes for which this user has access. - description: |- - **This endpoint returns a list of all scopes that this user has access to.** - - API Keys can be used to authenticate the use of [SendGrid’s v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissios, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The list of scopes for which this user has access.", - "uniqueItems": true, - "items": { - "type": "string" - } - } - }, - "required": [ - "scopes" - ] - } - example: |- - { - "scopes": [ - "mail.send", - "alerts.create", - "alerts.read" - ] - } - '401': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "errors": { - "type": "array", - "description": "This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes.", - "items": { - "type": "object", - "properties": { - "field": { - "type": "null", - "description": "This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required." - }, - "message": { - "type": "string", - "description": "Explains why the scopes cannot be returned." - } - }, - "required": [ - "message" - ] - } - } - }, - "required": [ - "errors" - ] - } - example: |- - { - "errors": [ - { - "field": null, - "message": "authorization required" - } - ] - } - queryParameters: {} -/geo: - displayName: geo - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve email statistics by country and state/province. - description: |- - **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** - - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_country" - } - } - example: |- - [ - { - "date": "2015-10-11", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-12", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-13", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-14", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-15", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-16", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-17", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-18", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-19", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-20", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-21", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 1, - "unique_clicks": 0, - "unique_opens": 1 - } - } - ] - }, - { - "date": "2015-10-22", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-23", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-24", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-25", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-26", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "date": "2015-10-27", - "stats": [ - { - "type": "province", - "name": "TX", - "metrics": { - "clicks": 0, - "opens": 0, - "unique_clicks": 0, - "unique_opens": 0 - } - } - ] - }, - { - "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 - } - } - ] - } - ] - queryParameters: - limit: - type: integer - description: How many results to include on each page. - offset: - type: integer - description: How many results to exclude. - aggregated_by: - type: string - description: 'How you would like the statistics to be grouped. Must be either "day", "week", or "month".' - enum: - - day - - week - - month - start_date: - type: string - description: The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD - required: true - end_date: - type: string - description: 'The end date of the statistics to retrieve. ' - default: The date the request is made. - country: - type: string - description: The country you would like to see statistics for. Currently only supported for US and CA. - enum: - - US - - CA -/browsers: - displayName: browsers - description: '' - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: 'Retrieve email statistics by browser. ' - description: |- - **This endpoint allows you to retrieve your email statistics segmented by browser type.** - - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/advanced_stats_clicks" - } - } - example: |- - [ - { - "date": "2014-10-01", - "stats": [ - { - "metrics": { - "clicks": 0, - "unique_clicks": 0 - }, - "name": "Chrome", - "type": "browser" - }, - { - "metrics": { - "clicks": 1, - "unique_clicks": 1 - }, - "name": "Firefox", - "type": "browser" - } - ] - }, - { - "date": "2014-10-02", - "stats": [ - { - "metrics": { - "clicks": 0, - "unique_clicks": 0 - }, - "name": "Chrome", - "type": "browser" - }, - { - "metrics": { - "clicks": 1, - "unique_clicks": 1 - }, - "name": "Firefox", - "type": "browser" - } - ] - } - ] - queryParameters: - start_date: - type: string - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - end_date: - type: string - description: The end date of the statistics to retrieve. Defaults to today. - limit: - type: string - description: The number of results to include on each page. - offset: - type: string - description: The number of results to exclude. - aggregated_by: - type: string - description: 'How to group the stats. Must be either "day", "week", or "month".' - enum: - - day - - week - - month - browsers: - type: string - description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times. -/categories: - displayName: categories - description: '' - uriParameters: {} - get: - displayName: Retrieve all categories - description: |- - **This endpoint allows you to retrieve a list of all of your categories.** - - Categories can help organize your email analytics by enabling you to “tag” emails by type or broad topic. You can define your own custom categories. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "category": { - "type": "string", - "description": "A category used to group emails by broad topic." - } - }, - "required": [ - "category" - ] - } - } - example: |- - [ - { - "category": "category 1" - }, - { - "category": "category 2" - } - ] - '400': - body: - application/json: - 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" - ] - } - } - } - } - example: |- - { - "errors": [ - { - "field": "sort_by", - "message": "invalid sort value" - } - ] - } - queryParameters: - limit: - type: integer - description: The number of categories to display per page. - default: 50 - category: - type: string - description: Allows you to perform a prefix search on this particular category. - offset: - type: integer - description: The point in the list that you would like to begin displaying results. - default: 0 - /stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve Email Statistics for Categories - description: |- - **This endpoint allows you to retrieve all of your email statistics for each of your categories.** - - If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - - Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "$ref": "#/definitions/category_stats" - } - } - example: |- - [ - { - "date": "2015-10-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - }, - { - "date": "2015-11-01", - "stats": [ - { - "type": "category", - "name": "docs", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - }, - { - "type": "category", - "name": "mattscategory", - "metrics": { - "blocks": 0, - "bounce_drops": 0, - "bounces": 0, - "clicks": 0, - "deferred": 0, - "delivered": 0, - "invalid_emails": 0, - "opens": 0, - "processed": 0, - "requests": 0, - "spam_report_drops": 0, - "spam_reports": 0, - "unique_clicks": 0, - "unique_opens": 0, - "unsubscribe_drops": 0, - "unsubscribes": 0 - } - } - ] - } - ] - queryParameters: - start_date: - type: string - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD - required: true - end_date: - type: string - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. - categories: - type: string - description: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. - required: true - limit: - type: integer - description: The number of results to include. - default: 500 - maximum: 500 - offset: - type: integer - description: The number of results to skip. - aggregated_by: - type: string - description: 'How to group the statistics. Must be either "day", "week", or "month".' - enum: - - day - - week - - month - /sums: - displayName: sums - description: '' - uriParameters: {} - get: - displayName: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' - description: |- - **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.** - - If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - - Categories allow you to group your emails together according to broad topics that you define. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/categories.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "": { - "$ref": "#/definitions/category_stats" - } - } - } - example: |- - { - "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" - } - ] - } - queryParameters: - sort_by_metric: - type: string - description: The metric that you want to sort by. Must be a single metric. - default: delivered - sort_by_direction: - type: string - description: The direction you want to sort. - default: desc - enum: - - desc - - asc - start_date: - type: string - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - end_date: - type: string - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. - limit: - type: integer - description: Limits the number of results returned. - default: 5 - offset: - type: integer - description: The point in the list to begin retrieving results. - default: 0 - aggregated_by: - type: string - description: 'How to group the statistics. Must be either "day", "week", or "month".' - enum: - - day - - week - - month -/stats: - displayName: stats - description: '' - uriParameters: {} - get: - displayName: Retrieve global email statistics - description: |- - **This endpoint allows you to retrieve all of your global email statistics between a given date range.** - - Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the stats were gathered." - }, - "stats": { - "type": "array", - "description": "The individual email activity stats.", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered. " - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - } - } - } - } - } - }, - "required": [ - "date", - "stats" - ] - } - } - example: |- - [ - { - "date": "2015-11-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 - } - } - ] - } - ] - queryParameters: - limit: - type: integer - description: The number of results to return. - offset: - type: integer - description: The point in the list to begin retrieving results. - aggregated_by: - type: string - description: 'How to group the statistics. Must be either "day", "week", or "month".' - enum: - - day - - week - - month - start_date: - type: string - description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. - required: true - end_date: - type: string - description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. -/access_settings: - displayName: access_settings - description: '' - /activity: - displayName: activity - description: '' - uriParameters: {} - get: - displayName: Retrieve all recent access attempts - description: |- - **This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API.** - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - headers: {} - responses: - '200': - body: - application/json: - 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" - ] - } - example: |- - { - "result": [ - { - "allowed": false, - "auth_method": "basic", - "first_at": 1444087966, - "ip": "1.1.1.1", - "last_at": 1444406672, - "location": "Australia" - }, - { - "allowed": false, - "auth_method": "basic", - "first_at": 1444087505, - "ip": "1.2.3.48", - "last_at": 1444087505, - "location": "Mukilteo, Washington" - } - ] - } - queryParameters: - limit: - type: integer - description: Limits the number of IPs to return. - default: 20 - /whitelist: - displayName: whitelist - description: '' - '/{rule_id}': - displayName: '{rule_id}' - description: '' - uriParameters: - rule_id: - type: string - description: The ID of the IP address that you want to remove from your whitelist. - displayName: The ID of the IP address that you want to remove from your whitelist. - get: - displayName: Retrieve a specific whitelisted IP - description: |- - **This endpoint allows you to retreive a specific IP address that has been whitelisted.** - - You must include the ID for the specific IP address you want to retrieve in your call. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the IP address." - }, - "ip": { - "type": "string", - "description": "The IP address." - }, - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP was whitelisted." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP address was last updated." - } - }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ] - } - example: |- - { - "id": 1, - "ip": "192.168.1.1", - "created_at": 1441824715, - "updated_at": 1441824715 - } - queryParameters: {} - delete: - displayName: Remove a specific IP from the whitelist - description: |- - **This endpoint allows you to remove a specific IP address from your IP whitelist.** - - When removing a specific IP address from your whitelist, you must include the ID in your call. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - queryParameters: {} - uriParameters: {} - delete: - displayName: Remove one or more IPs from the whitelist - description: |- - **This endpoint allows you to remove one or more IPs from your IP whitelist.** - - You can remove one IP at a time, or you can remove multiple IP addresses. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - headers: {} - responses: - '204': - body: - application/json: - schema: |- - { - "type": "object", - "properties": {} - } - example: '' - queryParameters: {} - get: - displayName: Retrieve a list of currently whitelisted IPs - description: |- - **This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.** - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - headers: {} - responses: - '200': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "An array listing all of your whitelisted IPs.", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the whitelisted IP." - }, - "ip": { - "type": "string", - "description": "The whitelisted IP." - }, - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP was whitelisted." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated." - } - }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ] - } - } - }, - "required": [ - "result" - ] - } - example: |- - { - "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 - } - ] - } - queryParameters: {} - post: - displayName: Add one or more IPs to the whitelist - description: |- - **This endpoint allows you to add one or more IP addresses to your IP whitelist.** - - When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once. - - IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - body: - application/json: - example: |- - { - "ips": [ - { - "ip": "192.168.1.1" - }, - { - "ip": "192.*.*.*" - }, - { - "ip": "192.168.1.3/32" - } - ] - } - schema: |- - { - "type": "object", - "properties": { - "ips": { - "type": "array", - "description": "An array containing the IP(s) you want to whitelist.", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "An IP address that you want to whitelist." - } - }, - "required": [ - "ip" - ] - } - } - }, - "required": [ - "ips" - ] - } - headers: {} - responses: - '201': - body: - application/json: - schema: |- - { - "type": "object", - "properties": { - "result": { - "type": "array", - "description": "An array listing all of your whitelisted IPs.", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the whitelisted IP." - }, - "ip": { - "type": "string", - "description": "The whitelisted IP." - }, - "created_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP was whitelisted." - }, - "updated_at": { - "type": "integer", - "description": "A Unix timestamp indicating when the IPs whitelisting status was most recently updated." - } - }, - "required": [ - "id", - "ip", - "created_at", - "updated_at" - ] - } - } - }, - "required": [ - "result" - ] - } - example: |- - { - "result": [ - { - "id": 1, - "ip": "192.168.1.1/32", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 2, - "ip": "192.0.0.0/8", - "created_at": 1441824715, - "updated_at": 1441824715 - }, - { - "id": 3, - "ip": "192.168.1.3/32", - "created_at": 1441824715, - "updated_at": 1441824715 - } - ] - } - queryParameters: {} -schemas: - - monitor: |- - { - "title": "Create monitor settings request", - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address to send emails at the frequency specified for monitoring.", - "format": "email" - }, - "frequency": { - "type": "number", - "description": "The frequency by which to send the emails. An email will be sent, every time your subuser sends this {frequency} emails. " - } - }, - "required": [ - "email", - "frequency" - ] - } - - contacts: |- - { - "type": "object", - "properties": { - "address": { - "type": "string" - }, - "address2": { - "type": "object" - }, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "email": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" - }, - "zip": { - "type": "string" - } - } - } - - subuser: |- - { - "title": "List all Subusers for a parent response", - "type": "object", - "properties": { - "disabled": { - "type": "boolean", - "description": "Whether or not the user is enabled or disabled." - }, - "id": { - "type": "number", - "description": "The ID of this subuser." - }, - "username": { - "type": "string", - "description": "The name by which this subuser will be referred." - }, - "email": { - "type": "string", - "description": "The email address to contact this subuser.", - "format": "email" - } - }, - "required": [ - "disabled", - "id", - "username", - "email" - ] - } - - contactdb_segments_conditions: |- - { - "type": "object", - "properties": { - "field": { - "type": "string" - }, - "value": { - "type": "string" - }, - "operator": { - "type": "string", - "enum": [ - "eq", - "ne", - "lt", - "gt", - "contains" - ] - }, - "and_or": { - "type": "string", - "enum": [ - "and", - "or", - "" - ] - } - }, - "required": [ - "field", - "value", - "operator" - ] - } - - subuser_post: |- - { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the subuser." - }, - "user_id": { - "type": "number", - "description": "The user ID for this subuser." - }, - "email": { - "type": "string", - "description": "The email address for this subuser.", - "format": "email" - }, - "signup_session_token": { - "type": "string" - }, - "authorization_token": { - "type": "string" - }, - "credit_allocation": { - "type": "object", - "properties": { - "type": { - "type": "string" - } - } - } - }, - "required": [ - "username", - "user_id", - "email" - ] - } - - contactdb_segments: |- - { - "title": "Create a Segment request", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of this segment." - }, - "list_id": { - "type": "integer", - "description": "The list id from which to make this segment. Not including this ID will mean your segment is created from the main contactdb rather than a list." - }, - "conditions": { - "type": "array", - "description": "The conditions for a recipient to be included in this segment.", - "items": { - "$ref": "#/definitions/contactdb_segments_conditions" - } - }, - "recipient_count": { - "type": "number", - "description": "The count of recipients in this list. This is not included on creation of segments." - } - }, - "required": [ - "name", - "conditions" - ] - } - - campaign_request: |- - { - "type": "object", - "properties": { - "title": { - "type": "string", - "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." - }, - "subject": { - "type": [ - "string", - "null" - ], - "description": "The subject of your campaign that your recipients will see." - }, - "sender_id": { - "type": [ - "null", - "integer" - ], - "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails." - }, - "list_ids": { - "type": [ - "array", - "null" - ], - "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", - "items": { - "type": "integer" - } - }, - "segment_ids": { - "type": [ - "array", - "null" - ], - "description": "The segment IDs that you are sending this list to. You can have both segment IDs and list IDs.", - "items": { - "type": "integer" - } - }, - "categories": { - "type": [ - "array", - "null" - ], - "description": "The categories you would like associated to this campaign.", - "items": { - "type": "string" - } - }, - "suppression_group_id": { - "type": [ - "null", - "integer" - ], - "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type." - }, - "custom_unsubscribe_url": { - "type": [ - "string", - "null" - ], - "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups." - }, - "ip_pool": { - "type": [ - "string", - "null" - ], - "description": "The pool of IPs that you would like to send this email from." - }, - "html_content": { - "type": [ - "string", - "null" - ], - "description": "The HTML of your marketing email." - }, - "plain_content": { - "type": [ - "string", - "null" - ], - "description": "The plain text content of your emails." - } - }, - "required": [ - "title" - ] - } - - contactdb_recipient_response: |- - { - "type": "object", - "properties": { - "error_count": { - "type": "number", - "default": 0, - "description": "The number of errors found while adding recipients." - }, - "error_indices": { - "type": "array", - "default": [], - "description": "The indices of the recipient(s) sent that caused the error. ", - "items": { - "type": "number" - } - }, - "new_count": { - "type": "number", - "default": 0, - "description": "The count of new recipients added to the contactdb." - }, - "persisted_recipients": { - "type": "array", - "default": [], - "description": "The recipient IDs of the recipients that already existed from this request.", - "items": { - "type": "string" - } - }, - "updated_count": { - "type": "number", - "default": 0, - "description": "The recipients who were updated from this request." - }, - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "message": { - "type": "string" - }, - "error_indices": { - "type": "array", - "items": { - "type": "number" - } - } - } - } - } - }, - "required": [ - "error_count", - "new_count", - "persisted_recipients", - "updated_count" - ] - } - - transactional_template_version: |- - { - "type": "object", - "properties": { - "template_id": { - "type": "string", - "description": "The name of the original transactional template." - }, - "active": { - "type": "integer", - "description": "Set the new version as the active version associated with the template. Only one version of a template can be active. The first version created for a template will automatically be set to Active.", - "enum": [ - 0, - 1 - ] - }, - "name": { - "type": "string", - "description": "Name of the new transactional template version." - }, - "html_content": { - "type": "string", - "description": "The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." - }, - "plain_content": { - "type": "string", - "description": "Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content." - }, - "subject": { - "type": "string", - "description": "Subject of the new transactional template version. Must include <%subject%> tag." - } - }, - "required": [ - "template_id", - "active", - "name", - "html_content", - "plain_content", - "subject" - ] - } - - api_key_name_id_scopes: |- - { - "allOf": [ - { - "type": "object", - "properties": { - "scopes": { - "type": "array", - "description": "The permissions this API Key has access to.", - "items": { - "type": "string" - } - } - } - }, - { - "$ref": "#/definitions/api_key_name_id" - } - ] - } - - credentials: |- - { - "type": "object", - "properties": { - "permissions": { - "type": "object", - "properties": { - "api": { - "type": "string" - }, - "mail": { - "type": "string" - }, - "web": { - "type": "string" - } - } - }, - "username": { - "type": "string" - } - } - } - - partner_settings_new_relic: |- - { - "type": "object", - "properties": { - "enable_subuser_statistics": { - "type": "boolean", - "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if this setting is enabled. " - }, - "license_key": { - "type": "string", - "description": "The license key provided with your New Relic account." - } - }, - "required": [ - "enabled", - "license_key" - ] - } - - suppression_group_unsubscribes: |- - { - "allOf": [ - { - "$ref": "#/definitions/suppression_group" - }, - { - "properties": { - "unsubscribes": { - "type": "integer", - "description": "The unsubscribes associated with this group." - } - }, - "required": [ - "unsubscribes" - ] - } - ], - "type": "object" - } - - 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." - } - } - } - - api_key_name_id: |- - { - "type": "object", - "properties": { - "api_key_id": { - "type": "string", - "description": "The ID of your API Key. " - }, - "name": { - "type": "string", - "description": "The name of your API Key." - } - } - } - - 'global:id': |- - { - "type": "integer" - } - - mail_settings_template: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the legacy email template setting is enabled." - }, - "html_content": { - "type": "string", - "description": "The HTML content that you want to use for your legacy email template." - } - } - } - - mail_settings_forward_spam: |- - { - "type": "object", - "properties": { - "email": { - "type": "string", - "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." - } - } - } - - 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." - } - } - } - - mail_settings_bcc: |- - { - "type": "object", - "properties": { - "email": { - "type": "string", - "description": "The email address that will be sent a blind carbon copy." - }, - "enabled": { - "type": "boolean", - "description": "Indicates if the BCC setting is enabled." - } - } - } - - mail_settings_address_whitelabel: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if you have an email address whitelist enabled. " - }, - "list": { - "type": "array", - "description": "All email address that are currently on the whitelist.", - "items": { - "type": "string" - } - } - } - } - - 'global:empty_request': |- - { - "type": "null" - } - - mail_batch_id: |- - { - "type": "object", - "properties": { - "batch_id": { - "type": "string", - "pattern": "^[a-zA-Z0-9\\-\\_]" - } - }, - "required": [ - "batch_id" - ] - } - - campaign_response: |- - { - "allOf": [ - { - "$ref": "#/definitions/campaign_request" - }, - { - "type": "object", - "properties": { - "status": { - "type": "string", - "description": "The status of your campaign." - }, - "id": { - "type": "integer" - } - }, - "required": [ - "status" - ] - } - ] - } - - contactdb_segments_with_id: |- - { - "allOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the segment." - } - }, - "required": [ - "id" - ] - }, - { - "$ref": "#/definitions/contactdb_segments" - } - ] - } - - contactdb_custom_field_with_id_value: |- - { - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field_with_id" - }, - { - "type": "object", - "properties": { - "value": { - "type": [ - "string", - "null" - ], - "description": "The value of this recipient's custom field" - } - } - } - ], - "title": "ContactDB Custom field schema." - } - - contactdb_custom_field_with_id: |- - { - "allOf": [ - { - "$ref": "#/definitions/contactdb_custom_field" - }, - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the custom field." - } - } - } - ], - "title": "ContactDB Custom field schema with ID." - } - - contactdb_custom_field: |- - { - "title": "ContactDB Custom field schema.", - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the field" - }, - "type": { - "type": "string", - "description": "The type of the field.", - "enum": [ - "date", - "text", - "number" - ] - } - } - } - - contactdb_recipient_count: |- - { - "type": "object", - "properties": { - "recipient_count": { - "type": "number", - "description": "The count of recipients." - } - }, - "required": [ - "recipient_count" - ] - } - - user_scheduled_send_status: |- - { - "allOf": [ - { - "$ref": "#/definitions/mail_batch_id" - }, - { - "type": "object", - "description": "The status of the scheduled send.", - "properties": { - "status": { - "type": "string", - "description": "The status of the scheduled send.", - "enum": [ - "cancel", - "pause" - ] - } - }, - "required": [ - "status" - ] - } - ] - } - - contactdb_list: |- - { - "title": "ContactDB lists", - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The reference ID of your list." - }, - "name": { - "type": "string", - "description": "The name of your list." - }, - "recipient_count": { - "type": "integer", - "description": "The count of recipients currently in the list." - } - }, - "required": [ - "id", - "name", - "recipient_count" - ] - } - - user_profile: |- - { - "type": "object", - "properties": { - "address": { - "type": "string" - }, - "address2": { - "type": "string" - }, - "city": { - "type": "string" - }, - "company": { - "type": "string" - }, - "country": { - "type": "string" - }, - "first_name": { - "type": "string" - }, - "last_name": { - "type": "string" - }, - "phone": { - "type": "string" - }, - "state": { - "type": "string" - }, - "website": { - "type": "string" - }, - "zip": { - "type": "string" - } - } - } - - 'global:ErrorResponse': |- - { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": [ - "string", - "null" - ], - "description": "The field that generated the error." - }, - "message": { - "type": "string", - "description": "The error message." - } - }, - "required": [ - "message" - ] - } - } - } - } - - suppression_bounce: |- - { - "type": "object", - "properties": { - "created": { - "type": "number", - "description": "The unix timestamp for when the bounce record was created at SendGrid." - }, - "email": { - "type": "string" - }, - "reason": { - "type": "string", - "description": "The reason for the bounce. This typically will be a bounce code, an enhanced code, and a description." - }, - "status": { - "type": "string", - "description": "Enhanced SMTP bounce response" - } - } - } - - contactdb_recipient: |- - { - "type": "object", - "properties": { - "recipients": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of this recipient." - }, - "created_at": { - "type": "number", - "description": "The time this record was created in your contactdb, in unixtime." - }, - "custom_fields": { - "type": "array", - "description": "The custom fields assigned to this recipient and their values.", - "items": { - "$ref": "#/definitions/contactdb_custom_field_with_id_value" - } - }, - "email": { - "type": "string", - "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", - "format": "email" - }, - "first_name": { - "type": [ - "string", - "null" - ], - "description": "The first name of this recipient. This is a default custom field that SendGrid provides." - }, - "last_name": { - "type": [ - "string", - "null" - ], - "description": "The last name of the recipient." - }, - "last_clicked": { - "type": [ - "number", - "null" - ], - "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime." - }, - "last_emailed": { - "type": [ - "number", - "null" - ], - "description": "The last time this user was emailed by one of your campaigns, in unixtime." - }, - "last_opened": { - "type": [ - "number", - "null" - ], - "description": "The last time this recipient opened an email from you, in unixtime." - }, - "updated_at": { - "type": "number", - "description": "The last update date for this recipient's record." - } - }, - "required": [ - "email" - ] - } - } - } - } - - 'whitelabel::domain': |- - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The ID of the domain whitelabel." - }, - "user_id": { - "type": "number", - "description": "The ID of the user that this whitelabel will be associated with." - }, - "subdomain": { - "type": "string", - "description": "The subdomain to use for this domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel is being created for." - }, - "username": { - "type": "string", - "description": "The username that this whitelabel will be associated with." - }, - "ips": { - "type": "array", - "description": "The IPs to be included in the custom SPF record for this domain whitelabel.", - "items": { - "type": "object" - } - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates whether this domain whitelabel will use custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this domain whitelabel is the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this domain whitelabel was created using the legacy whitelabel tool." - }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this domain whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel that are used to authenticate the sending domain.", - "required": [ - "mail_cname", - "dkim1", - "dkim2" - ], - "properties": { - "mail_cname": { - "type": "object", - "description": "The CNAME for your sending domain that points to sendgrid.net.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid CNAME." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this CNAME is created for.", - "format": "hostname" - }, - "data": { - "type": "string", - "description": "The CNAME record." - } - } - }, - "dkim1": { - "type": "object", - "description": "A DNS record.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this DNS record was created for." - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } - }, - "dkim2": { - "type": "object", - "description": "A DNS record.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "The domain that this DNS record was created for." - }, - "data": { - "type": "string", - "description": "The DNS record." - } - } - } - } - } - }, - "required": [ - "id", - "user_id", - "subdomain", - "domain", - "username", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ] - } - - 'whitelabel:domain_spf': |- - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The ID of the domain whitelabel." - }, - "domain": { - "type": "string", - "description": "The domain that this whitelabel was created for." - }, - "subdomain": { - "type": "string", - "description": "The subdomain that was used to create this whitelabel." - }, - "username": { - "type": "string", - "description": "The username of the account that this whitelabel is associated with." - }, - "user_id": { - "type": "integer", - "description": "The user_id of the account that this whitelabel is associated with." - }, - "ips": { - "type": "array", - "description": "The IP addresses that are included in the SPF record for this whitelabel.", - "items": {} - }, - "custom_spf": { - "type": "boolean", - "description": "Indicates if this whitelabel uses custom SPF." - }, - "default": { - "type": "boolean", - "description": "Indicates if this is the default whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." - }, - "automatic_security": { - "type": "boolean", - "description": "Indicates if this whitelabel uses automated security." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "dns": { - "type": "object", - "description": "The DNS records for this whitelabel.", - "required": [ - "mail_server", - "subdomain_spf", - "domain_spf", - "dkim" - ], - "properties": { - "mail_server": { - "type": "object", - "description": "Designates which mail server is responsible for accepting messages from a domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain sending the messages." - }, - "type": { - "type": "string", - "description": "They type of DNS record." - }, - "data": { - "type": "string", - "description": "The mail server responsible for accepting messages from the sending domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid DNS record." - } - } - }, - "subdomain_spf": { - "type": "object", - "description": "The SPF record for the subdomain used to create this whitelabel.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid SPF record." - } - } - }, - "domain_spf": { - "type": "object", - "description": "The SPF record for the root domain.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The root domain that this SPF record will be used to authenticate." - }, - "type": { - "type": "string", - "description": "The type of data in the SPF record." - }, - "data": { - "type": "string", - "description": "The SPF record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the SPF record is valid." - } - } - }, - "dkim": { - "type": "object", - "description": "The DKIM record for messages sent using this whitelabel.", - "required": [ - "host", - "type", - "data", - "valid" - ], - "properties": { - "host": { - "type": "string", - "description": "The DNS labels for the DKIM signature." - }, - "type": { - "type": "string", - "description": "The type of data in the DKIM record." - }, - "data": { - "type": "string", - "description": "The DKIM record." - }, - "valid": { - "type": "boolean", - "description": "Indicates if the DKIM record is valid." - } - } - } - } - } - }, - "required": [ - "id", - "domain", - "subdomain", - "username", - "user_id", - "ips", - "custom_spf", - "default", - "legacy", - "automatic_security", - "valid", - "dns" - ] - } - - transactional_template: |- - { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "The ID of the transactional template." - }, - "name": { - "type": "string", - "description": "The name for the transactional template.", - "maxLength": 100 - }, - "versions": { - "type": "array", - "description": "The different versions of this transactional template.", - "items": { - "$ref": "#/definitions/transactional_template_version" - } - } - }, - "required": [ - "id", - "name" - ] - } - - suppression_group: |- - { - "type": "object", - "properties": { - "id": { - "type": "number", - "description": "The id of the suppression group." - }, - "name": { - "type": "string", - "description": "The name of the suppression group. Each group created by a user must have a unique name.", - "maxLength": 30 - }, - "description": { - "type": "string", - "description": "A description of the suppression group.", - "maxLength": 100 - }, - "last_email_sent_at": { - "type": "null" - }, - "is_default": { - "type": "boolean", - "default": false, - "description": "Indicates if this is the default suppression group." - } - }, - "required": [ - "id", - "name", - "description" - ] - } - - advanced_stats_country: |- - { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "opens", - "unique_clicks", - "unique_opens" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - } - - advanced_stats_opens: |- - { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "opens", - "unique_opens" - ], - "properties": { - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - } - - advanced_stats_clicks: |- - { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "unique_clicks" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - } - - advanced_stats_mailbox_provider: |- - { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the events occurred." - }, - "stats": { - "type": "array", - "description": "The statistics of the email events.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their stats.", - "required": [ - "clicks", - "opens", - "unique_clicks", - "unique_opens", - "blocks", - "bounces", - "deferred", - "delivered", - "drops", - "spam_reports" - ], - "properties": { - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered." - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "drops": { - "type": "integer", - "description": "The number of emails that were not delivered due to the recipient email address being on a suppression list." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - } - } - } - }, - "required": [ - "type", - "name", - "metrics" - ] - } - } - }, - "required": [ - "date", - "stats" - ] - } - - stats: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date that the statistics were gathered." - }, - "stats": { - "type": "array", - "description": "The list of statistics.", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "description": "The type of segmentation." - }, - "name": { - "type": "string", - "description": "The name of the specific segmentation." - }, - "metrics": { - "type": "object", - "description": "The individual events and their statistics.", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked in your emails." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered. " - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - } - } - } - } - } - } - } - } - - link_whitelabel: |- - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the link whitelabel." - }, - "domain": { - "type": "string", - "description": "The root domain for this link whitelabel." - }, - "subdomain": { - "type": "string", - "description": "The subdomain used to generate the DNS records for this link whitelabel. This subdomain must be different from the subdomain used for your domain whitelabel." - }, - "username": { - "type": "string", - "description": "The username of the account that this link whitelabel is associated with." - }, - "user_id": { - "type": "integer", - "description": "The id of the user that this whitelabel is associated with." - }, - "default": { - "type": "boolean", - "description": "Indicates if this is the default link whitelabel.", - "enum": [ - true, - false - ] - }, - "valid": { - "type": "boolean", - "description": "Indicates if this link whitelabel is valid.", - "enum": [ - true, - false - ] - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this link whitelabel was created using the legacy whitelabel tool.", - "enum": [ - true, - false - ] - }, - "dns": { - "type": "object", - "description": "The DNS records generated for this link whitelabel.", - "required": [ - "domain_cname" - ], - "properties": { - "domain_cname": { - "type": "object", - "description": "The DNS record generated to point to your link whitelabel subdomain.", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [ - true, - false - ] - }, - "type": { - "type": "string", - "description": "The type of DNS record that was generate.", - "enum": [ - "cname", - "txt", - "mx" - ] - }, - "host": { - "type": "string", - "description": "The domain that this whitelabel will use when whitelabeling the links in your email." - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to." - } - } - }, - "owner_cname": { - "type": "object", - "description": "The DNS record generated to verify who created the link whitelabel.", - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the DNS record is valid.", - "enum": [ - true, - false - ] - }, - "type": { - "type": "string", - "description": "The type of DNS record generated.", - "enum": [ - "cname", - "txt", - "mx" - ] - }, - "host": { - "type": "string", - "description": "Used to verify the link whitelabel. The subdomain of this domain is the user id of the user who created the link whitelabel." - }, - "data": { - "type": "string", - "description": "The domain that the DNS record points to." - } - }, - "required": [ - "valid", - "host", - "data" - ] - } - } - } - }, - "required": [ - "id", - "domain", - "subdomain", - "username", - "user_id", - "default", - "valid", - "legacy", - "dns" - ] - } - - ip_warmup_response: |- - { - "type": "array", - "items": { - "type": "object", - "properties": { - "ip": { - "type": "string", - "description": "The IP address." - }, - "start_date": { - "type": "integer", - "description": "A Unix timestamp indicating when the IP address was entered into warmup mode." - } - }, - "required": [ - "ip", - "start_date" - ] - } - } - - category_stats: |- - { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "The date the statistics were gathered." - }, - "stats": { - "type": "array", - "items": { - "type": "object", - "properties": { - "metrics": { - "type": "object", - "properties": { - "blocks": { - "type": "integer", - "description": "The number of emails that were not allowed to be delivered by ISPs." - }, - "bounce_drops": { - "type": "integer", - "description": "The number of emails that were dropped because of a bounce." - }, - "bounces": { - "type": "integer", - "description": "The number of emails that bounced instead of being delivered." - }, - "clicks": { - "type": "integer", - "description": "The number of links that were clicked." - }, - "deferred": { - "type": "integer", - "description": "The number of emails that temporarily could not be delivered." - }, - "delivered": { - "type": "integer", - "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." - }, - "invalid_emails": { - "type": "integer", - "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." - }, - "opens": { - "type": "integer", - "description": "The total number of times your emails were opened by recipients." - }, - "processed": { - "type": "integer", - "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." - }, - "requests": { - "type": "integer", - "description": "The number of emails that were requested to be delivered." - }, - "spam_report_drops": { - "type": "integer", - "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." - }, - "spam_reports": { - "type": "integer", - "description": "The number of recipients who marked your email as spam." - }, - "unique_clicks": { - "type": "integer", - "description": "The number of unique recipients who clicked links in your emails." - }, - "unique_opens": { - "type": "integer", - "description": "The number of unique recipients who opened your emails." - }, - "unsubscribe_drops": { - "type": "integer", - "description": "The number of emails dropped due to a recipient unsubscribing from your emails." - }, - "unsubscribes": { - "type": "integer", - "description": "The number of recipients who unsubscribed from your emails." - } - }, - "required": [ - "blocks", - "bounce_drops", - "bounces", - "clicks", - "deferred", - "delivered", - "invalid_emails", - "opens", - "processed", - "requests", - "spam_report_drops", - "spam_reports", - "unique_clicks", - "unique_opens", - "unsubscribe_drops", - "unsubscribes" - ] - }, - "name": { - "type": "string", - "description": "The name of the category." - }, - "type": { - "type": "string", - "description": "How you are segmenting your statistics." - } - }, - "required": [ - "type" - ] - } - } - }, - "required": [ - "date" - ] - } - - ip_whitelabel: |- - { - "type": "object", - "properties": { - "id": { - "type": "integer", - "description": "The id of the IP whitelabel." - }, - "ip": { - "type": "string", - "description": "The IP address that this whitelabel was created for." - }, - "rdns": { - "type": "string", - "description": "The reverse DNS record for the IP address. This points to the IP whitelabel subdomain." - }, - "users": { - "type": "array", - "description": "The users who are able to send mail from the IP.", - "items": { - "type": "object", - "properties": { - "username": { - "type": "string", - "description": "The username of the user who can send mail from this IP." - }, - "user_id": { - "type": "integer", - "description": "The ID of the user who can send mail from this IP." - } - }, - "required": [ - "username", - "user_id" - ] - } - }, - "subdomain": { - "type": "string", - "description": "The subdomain created for this IP whitelabel. This is where the rDNS record points." - }, - "domain": { - "type": "string", - "description": "The root, or sending, domain." - }, - "valid": { - "type": "boolean", - "description": "Indicates if this is a valid whitelabel." - }, - "legacy": { - "type": "boolean", - "description": "Indicates if this whitelabel was created using the legacy whitelabel tool." - }, - "a_record": { - "type": "object", - "required": [ - "valid", - "type", - "host", - "data" - ], - "properties": { - "valid": { - "type": "boolean", - "description": "Indicates if the a_record is valid." - }, - "type": { - "type": "string", - "description": "The type of DNS record." - }, - "host": { - "type": "string", - "description": "This is the web address that will be mapped to the IP address." - }, - "data": { - "type": "string", - "description": "The IP address being whitelabeled." - } - } - } - }, - "required": [ - "id", - "ip", - "rdns", - "users", - "subdomain", - "domain", - "valid", - "legacy", - "a_record" - ] - } - - google_analytics_settings: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if Google Analytics is enabled." - }, - "utm_campaign": { - "type": "string", - "description": "The name of the campaign." - }, - "utm_content": { - "type": "string", - "description": "Used to differentiate ads" - }, - "utm_medium": { - "type": "string", - "description": "Name of the marketing medium (e.g. \"Email\")." - }, - "utm_source": { - "type": "string", - "description": "Name of the referrer source. " - }, - "utm_term": { - "type": "string", - "description": "Any paid keywords." - } - } - } - - subscription_tracking_settings: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if subscription tracking is enabled." - }, - "html_content": { - "type": "string", - "description": "The information and HTML for your unsubscribe link. " - }, - "landing": { - "type": "string", - "description": "The HTML that will be displayed on the page that your customers will see after clicking unsubscribe, hosted on SendGrid’s server." - }, - "plain_content": { - "type": "string", - "description": "The information in plain text for your unsubscribe link. You should have the “<% %>” tag in your content, otherwise the user will have no URL for unsubscribing." - }, - "replace": { - "type": "string", - "description": "Your custom defined replacement tag for your templates. Use this tag to place your unsubscribe content anywhere in your emailtemplate." - }, - "url": { - "type": "string", - "description": "The URL where you would like your users sent to unsubscribe." - } - } - } - - mail_settings_footer: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the Footer mail setting is currently enabled." - }, - "html_content": { - "type": "string", - "description": "The custom HTML content of your email footer." - }, - "plain_content": { - "type": "string", - "description": "The plain text content of your email footer." - } - } - } - - mail_settings_spam_check: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if your Spam Checker mail setting is enabled." - }, - "max_score": { - "type": "integer", - "default": 5, - "description": "The spam threshold. Can range from 1 to 10. The lower the number, the more strict the filtering.", - "minimum": 1, - "maximum": 10 - }, - "url": { - "type": "string", - "description": "The inbound parse URL where you would like the spam messages to be sent to." - } - }, - "required": [ - "enabled" - ] - } - - mail_settings_bounce_purge: |- - { - "type": "object", - "properties": { - "enabled": { - "type": "boolean", - "description": "Indicates if the bounce purge mail setting is enabled." - }, - "soft_bounces": { - "type": [ - "integer", - "null" - ], - "description": "The number of days, after which SendGrid will purge all contacts from your soft bounces suppression lists." - }, - "hard_bounces": { - "type": [ - "integer", - "null" - ], - "description": "The number of days, after which SendGrid will purge all contacts from your hard bounces suppression lists." - } - } - } - - ip_pool: |- - { - "type": "object", - "properties": { - "name": { - "type": "string", - "description": "The name of the IP pool.", - "maxLength": 64 - } - }, - "required": [ - "name" - ] - } - - event_webhook_settings: |- - { - "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" - } - }, - "required": [ - "enabled", - "url", - "group_resubscribe", - "delivered", - "group_unsubscribe", - "spam_report", - "bounce", - "deferred", - "unsubscribe", - "processed", - "open", - "click", - "dropped" - ] - } - - 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." - } - } - } - } - } - } - - email_object: |- - { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email" - }, - "name": { - "type": "string", - "description": "The name of the person to whom you are sending an email." - } - }, - "required": [ - "email" - ] - } - - errors: |- - { - "type": "object", - "properties": { - "errors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": [ - "null", - "string" - ], - "description": "The field that has the error." - }, - "message": { - "type": "string", - "description": "The message the API caller will receive." - } - } - } - } - } - } -traits: []