<% body %>Example
+ security: + - Authorization: [] + patch: + summary: 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). + operationId: PATCH_mail_settings-template + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' + 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. + example: + enabled: true + html_content: <% body %> + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + enabled: + type: boolean + html_content: + type: string examples: application/json: - errors: - - field: null - message: recipient_id is not valid + enabled: false + html_content: | +<% body %>Example
security: - Authorization: [] + '/campaigns/{campaign_id}/schedules': + parameters: + - name: campaign_id + in: path + required: true + type: integer get: - summary: Retrieve a single recipient + summary: View Scheduled Time of a Campaign description: |- - **This endpoint allows you to retrieve a single recipient by ID from your contact database.** + **This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-recipients-recipient_id + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: GET_campaigns-campaign_id-schedules consumes: - application/json produces: @@ -2856,116 +1719,93 @@ paths: '200': description: '' schema: - $ref: '#/definitions/contactdb_recipient' - '400': - description: '"recipient_id" : "Returned if recipient_id is not valid"' - schema: + title: View Scheduled Time of a Campaign response type: object - '401': - description: '' + properties: + send_at: + type: integer + format: int64 + required: + - send_at + examples: + application/json: + send_at: 1490778528 + '404': + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: authorization required - '404': - description: '"recipient_id" : "Returned if record for recipient id does not exist"' - schema: - type: object + message: not found security: - Authorization: [] - /contactdb/recipients/search: - parameters: [] - get: - tags: - - Contacts API - Recipients - summary: Retrieve recipients matching search criteria + delete: + summary: Unschedule a Scheduled Campaign description: |- - **This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** + **This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.** - field_name: + 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). - * is a variable that is substituted for your actual custom field name from your recipient. - * Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) - * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert - your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to - Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through - Mon, 02 Feb 2015 23:59:59 GMT. + For more information: - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: GET_contactdb-recipients-search + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: DELETE_campaigns-campaign_id-schedules consumes: - application/json produces: - application/json parameters: - - name: '{field_name}' - in: query - type: string + - name: body + in: body + schema: + type: 'null' responses: - '200': + '204': description: '' - schema: - type: object - properties: - recipients: - type: array - items: - $ref: '#/definitions/contactdb_recipient' - examples: - application/json: - recipients: - - created_at: 1422313607 - email: jones@example.com - first_name: null - id: YUBh - last_clicked: null - last_emailed: null - last_name: Jones - last_opened: null - updated_at: 1422313790 - custom_fields: - - id: 23 - name: pet - value: Fluffy - type: text - '400': + schema: + type: 'null' + '403': description: |- - "" : "Returned if no search params are specified" - "field" : "Returned if the provided field is invalid or does not exist" + "": "This campaign is already In Progress." + "": "This campaign is already Sent." + "": "This campaign is already Paused." + "": "This campaign is already Canceled." schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: 'The following parameters are not custom fields or reserved fields: [{field_name}]' - - message: No search params are specified - '401': - description: '' + - field: null + message: This campaign is already In Progress. + - field: null + message: This campaign is already Sent. + - field: null + message: This campaign is already Paused. + - field: null + message: This campaign is already Canceled. + '404': + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: authorization required + message: not found security: - Authorization: [] - /contactdb/recipients: - parameters: [] - delete: - tags: - - Contacts API - Recipients - summary: Delete Recipient + patch: + summary: Update a Scheduled Campaign description: |- - **This endpoint allows you to deletes one or more recipients.** + **This endpoint allows to you change the scheduled time and date for a campaign to be sent.** - The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. + For more information: - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: DELETE_contactdb-recipients + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: PATCH_campaigns-campaign_id-schedules consumes: - application/json produces: @@ -2974,52 +1814,81 @@ paths: - name: body in: body schema: - type: array - items: - type: string + title: Update a Scheduled Campaign request + type: object + properties: + send_at: + type: integer + format: int64 + required: + - send_at example: - - recipient_id1 - - recipient_id2 + send_at: 1489451436 responses: '200': description: '' schema: + title: Update a Scheduled Campaign response type: object + properties: + id: + type: integer + description: The campaign ID + send_at: + type: integer + description: The unix timestamp to send the campaign. + status: + type: string + description: The status of the schedule. + required: + - id + - send_at + - status '400': description: |- - "" : "Returned if no recipients are deleted" - "" : "Returned if all of the provided recipient ids are invalid" - "" : "Returned if request body is not valid json" + "": "The JSON you have submitted cannot be parsed." + "send_at": "Please choose a future time for sending your campaign." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: No recipient ids provided - '401': - description: '' + - field: send_at + message: Please choose a future time for sending your campaign. + - field: null + message: The JSON you have submitted cannot be parsed. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing' + '403': + description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: send_at + message: You cannot update the send_at value of non-scheduled campaign. + '404': + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: authorization required + message: not found security: - Authorization: [] - patch: - tags: - - Contacts API - Recipients - summary: Update Recipient + post: + summary: Schedule a Campaign description: |- - **This endpoint allows you to update one or more recipients.** - - The body of an API call to this endpoint must include an array of one or more recipient objects. + **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** - It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. + For more information: - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: PATCH_contactdb-recipients + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: POST_campaigns-campaign_id-schedules consumes: - application/json produces: @@ -3028,39 +1897,73 @@ paths: - name: body in: body schema: - type: array - items: - type: object - properties: - email: - type: string - format: email - last_name: - type: string - description: The last name of the recipient. This is one of the default custom fields. - first_name: - type: string - description: The first name of the recipient. This is one of the default custom fields. - required: - - email + title: Schedule a Campaign request + type: object + properties: + send_at: + type: integer + description: The unix timestamp for the date and time you would like your campaign to be sent out. + required: + - send_at example: - - email: jones@example.com - last_name: Jones - first_name: Guy + send_at: 1489771528 responses: '201': description: '' schema: - $ref: '#/definitions/contactdb_recipient_response' + title: Schedule a Campaign response + type: object + properties: + id: + type: integer + description: The campaign ID. + send_at: + type: integer + description: The date time you scheduled your campaign to be sent. + status: + type: string + description: The status of your campaign. + enum: + - Scheduled + required: + - id + - send_at + - status + examples: + application/json: + id: 1234 + send_at: 1489771528 + status: Scheduled '400': - description: '"" : "Returned if request body is not valid json"' + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "send_at": "Please choose a future time for sending your campaign." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "The JSON you have submitted cannot be parsed." + "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: + - field: subject + message: subject can't be blank + - field: sender_id + message: sender_id can't be blank + - field: plain_content + message: 'plain_content can''t be blank, please provide plain text or html content' + - field: list_id + message: You must select at least 1 segment or 1 list to send to. + - field: unsubscribe_tag + message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' + - field: suppression_group_id + message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - field: null - message: Request body is not valid json + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' '401': description: '' schema: @@ -3070,76 +1973,72 @@ paths: errors: - field: null message: authorization required + '403': + description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH. + '404': + description: '"": "not found"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: not found security: - Authorization: [] + /contactdb/lists: + parameters: [] get: tags: - - Contacts API - Recipients - summary: Retrieve recipients + - Contacts API - Lists + summary: Retrieve all lists description: |- - **This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** - - Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of - the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. + **This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned.** The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-recipients + operationId: GET_contactdb-lists consumes: - application/json produces: - application/json - parameters: - - name: page - in: query - description: Page index of first recipients to return (must be a positive integer) - type: integer - - name: page_size - in: query - description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) - type: integer + parameters: [] responses: '200': description: '' schema: - title: List Recipients response + title: List All Lists response type: object properties: - recipients: + lists: type: array items: - type: object + $ref: '#/definitions/contactdb_list' required: - - recipients - '400': - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - "page_size" : "Returned if page_size is less than 1 or greater than 1000" - schema: - type: object - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + - lists + examples: + application/json: + lists: + - id: 1 + name: the jones + recipient_count: 1 security: - Authorization: [] - post: + delete: tags: - - Contacts API - Recipients - summary: Add recipients + - Contacts API - Lists + summary: Delete Multiple lists description: |- - **This endpoint allows you to add a Marketing Campaigns recipient.** - - It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. + **This endpoint allows you to delete multiple recipient lists.** The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: POST_contactdb-recipients + operationId: DELETE_contactdb-lists consumes: - application/json produces: @@ -3150,57 +2049,26 @@ paths: schema: type: array items: - type: object - properties: - email: - type: string - description: The email address of the recipient. - format: email - first_name: - type: string - description: The first name of the recipient. - last_name: - type: string - description: The last name of the recipient. - required: - - email + type: number example: - - email: example@example.com - first_name: '' - last_name: User - age: 25 - - email: example2@example.com - first_name: Example - last_name: User - age: 25 + - 1 + - 2 + - 3 + - 4 responses: - '201': + '204': description: '' schema: - $ref: '#/definitions/contactdb_recipient_response' - examples: - application/json: - error_count: 1 - error_indices: - - 2 - new_count: 2 - persisted_recipients: - - YUBh - - bWlsbGVyQG1pbGxlci50ZXN0 - updated_count: 0 - errors: - - message: Invalid email. - error_indices: - - 2 + type: 'null' '400': - description: '"" : "Returned if request body is not valid json"' + description: '"id" : "Returned if all list ids are not valid"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null - message: Request body is not valid json + message: list id was invalid '401': description: '' schema: @@ -3212,62 +2080,58 @@ paths: message: authorization required security: - Authorization: [] - '/contactdb/lists/{list_id}/recipients/{recipient_id}': - parameters: - - name: list_id - in: path - description: The ID of the list from which you are deleting a recipient. - required: true - type: integer - - name: recipient_id - in: path - description: The ID of the recipient you want to delete. - required: true - type: string - delete: - summary: Delete a Single Recipient from a Single List + post: + tags: + - Contacts API - Lists + summary: Create a List description: |- - **This endpoint allows you to delete a single recipient from a list.** + **This endpoint allows you to create a list for your recipients.** The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: DELETE_contactdb-lists-list_id-recipients-recipient_id + operationId: POST_contactdb-lists consumes: - application/json produces: - application/json parameters: - - name: list_id - in: query - description: The ID of the list you are taking this recipient away from. - required: true - type: number - - name: recipient_id - in: query - description: The ID of the recipient to take off the list. - required: true - type: number - name: body in: body schema: - type: 'null' + title: Create a List request + type: object + properties: + name: + type: string + required: + - name + example: + name: your list name responses: - '204': + '201': description: '' schema: - type: 'null' + $ref: '#/definitions/contactdb_list' + examples: + application/json: + id: 1 + name: your list name + recipient_count: 0 '400': description: |- - "list_id" : "Returned if list_id is not valid" - "recipient_id" : "Returned if recipient_id is not valid" + "name" : "Returned if list name is a duplicate of an existing list or segment" + "name" : "Returned if list name is not a string" + "" : "Returned if request body is invalid JSON" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: no valid recipients were provided + - field: null + message: Returned if request body is invalid JSON + - field: name + message: Returned if list name is not a string + - field: name + message: Returned if list name is a duplicate of an existing list or segment '401': description: '' schema: @@ -3277,28 +2141,26 @@ paths: errors: - field: null message: authorization required - '404': - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist security: - Authorization: [] - post: - summary: Add a Single Recipient to a List + '/campaigns/{campaign_id}': + parameters: + - name: campaign_id + in: path + description: The ID of the campaign that you would like to delete. + required: true + type: integer + delete: + summary: Delete a Campaign description: |- - **This endpoint allows you to add a single recipient to a list.** + **This endpoint allows you to delete a specific campaign.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: POST_contactdb-lists-list_id-recipients-recipient_id + 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) + operationId: DELETE_campaigns-campaign_id consumes: - application/json produces: @@ -3309,206 +2171,258 @@ paths: schema: type: 'null' responses: - '201': + '204': description: '' schema: type: 'null' - '400': - description: |- - "list_id" : "Returned if list_id is invalid" - "recipient_id" : "Returned if recipient_id is invalid" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: list_id - message: Returned if list_id is invalid - - field: recipient_id - message: Returned if recipient_id is invalid '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: - field: null message: authorization required '404': - description: |- - "list_id" : "Returned if list_id does not exist" - "recipient_id" : "Returned if recipient_id does not exist" + description: '"": "not found"' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: list_id - message: Returned if list_id does not exist - - field: recipient_id - message: Returned if recipient_id does not exist + type: object security: - Authorization: [] - '/contactdb/lists/{list_id}': - parameters: - - name: list_id - in: path - description: The ID of the recipient list that you want to delete. - required: true - type: string - delete: - summary: Delete a List + get: + summary: Retrieve a single campaign description: |- - **This endpoint allows you to delete a specific recipient list with the given ID.** + **This endpoint allows you to retrieve a specific campaign.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: DELETE_contactdb-lists-list_id + 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) + operationId: GET_campaigns-campaign_id consumes: - application/json produces: - application/json - parameters: - - name: delete_contacts - in: query - description: Adds the ability to delete all contacts on the list in addition to deleting the list. - type: boolean - enum: - - true - - false - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: - '202': + '200': description: '' schema: - type: 'null' - '400': - description: |- - "list_id" : "Returned if list_id is not valid" - "delete_contacts" : "Returned if delete_contacts is not valid" - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/campaign_response' examples: application/json: - errors: - - field: delete_contacts - message: delete_contacts not a bool - - field: list_id - message: Returned if list_id is not valid + id: 986724 + title: March Newsletter + subject: New Products for Spring! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:Check out our spring line!
+ plain_content: Check out our spring line! + status: Draft '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: - field: null message: authorization required '404': - description: '"list_id" : "Returned if list_id does not exist"' + description: '"": "not found"' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object examples: application/json: errors: - - message: 'List not found: 5' + - field: null + message: not found security: - Authorization: [] patch: - summary: Update a List + summary: Update a Campaign description: |- - **This endpoint allows you to update the name of one of your recipient lists.** + 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: - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: PATCH_contactdb-lists-list_id + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: PATCH_campaigns-campaign_id consumes: - application/json produces: - application/json parameters: - - name: list_id - in: query - description: The ID of the list you are updating. - required: true - type: number - name: body in: body schema: - title: Update a List request + title: Update a Campaign request type: object properties: - name: + title: type: string - description: 'The new name for your list. ' + description: The title of the campaign. + subject: + type: string + description: The subject line for your campaign. + categories: + type: array + description: The categories you want to tag on this campaign. + items: + type: string + html_content: + type: string + description: The HTML content of this campaign. + plain_content: + type: string + description: The plain content of this campaign. required: - - name + - title + - subject + - categories + - html_content + - plain_content example: - name: newlistname + 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! responses: '200': description: '' schema: - type: object + $ref: '#/definitions/campaign_response' + examples: + application/json: + id: 986724 + title: May Newsletter + subject: New Products for Summer! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - summer line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:Check out our summer line!
+ plain_content: Check out our summer line! + status: Draft '400': description: |- - "name" : "Returned if list name is a duplicate of existing list or segment" - "name" : "Returned if list name is invalid or not provided" - "list_id" : "Returned if list_id is not valid" - "" : "Returned if request body is invalid JSON" + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." + schema: + type: object + examples: + application/json: + errors: + - field: title + message: title can't be blank + - field: title + message: title is too long (maximum is 100 characters) + - field: categories + message: categories exceeds 10 category limit + - field: html_content + message: html_content exceeds the 1MB limit + - field: plain_content + message: plain_content exceeds the 1MB limit + - field: sender_id + message: sender_id does not exist + - field: sender_id + message: sender_id is not a verified sender identity + - field: list_ids + message: list_ids do not all exist + - field: segment_ids + message: segment_ids do not all exist + - field: ip_pool + message: The ip pool you provided is invalid + - field: suppression_group_id + message: suppression_group_id does not exist + - field: unsubscribes + message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' + - field: null + message: The JSON you have submitted cannot be parsed. + '401': + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: invalid id + - field: null + message: authorization required + '403': + description: '"": "You may only update a campaign when it is in draft mode."' + schema: + type: object + examples: + application/json: + errors: + - field: null + message: You may only update a campaign when it is in draft mode. '404': - description: '"list_id" : "Returned if list_id does not exist"' + description: '"": "not found"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: List ID does not exist + - field: null + message: not found security: - Authorization: [] + /contactdb/recipients/count: + parameters: [] get: - summary: Retrieve a single list + tags: + - Contacts API - Recipients + summary: Retrieve a Count of Recipients description: |- - This endpoint allows you to retrieve a single recipient list. + **This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - operationId: GET_contactdb-lists-list_id + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: GET_contactdb-recipients-count consumes: - application/json produces: - application/json - parameters: - - name: list_id - in: query - description: The ID of the list to retrieve. - type: number + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/contactdb_list' - examples: - application/json: - id: 1 - name: listname - recipient_count: 0 - '400': - description: '"list_id" : "Returned if list_id is not valid"' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/contactdb_recipient_count' examples: application/json: - errors: - - message: invalid id + recipient_count: 1234 '401': description: '' schema: @@ -3518,26 +2432,19 @@ paths: errors: - field: null message: authorization required - '404': - description: '"list_id" : "Returned if list_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: List ID does not exist security: - Authorization: [] - /contactdb/custom_fields: + '/whitelabel/domains/{domain_id}': parameters: [] get: - summary: Retrieve all custom fields - description: |- - **This endpoint allows you to retrieve all custom fields.** + summary: Retrieve a domain whitelabel. + description: | + **This endpoint allows you to retrieve a specific domain whitelabel.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: GET_contactdb-custom_fields + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: GET_whitelabel-domains-domain_id consumes: - application/json produces: @@ -3547,54 +2454,42 @@ paths: '200': description: '' schema: - title: List All Custom Fields response - type: object - properties: - custom_fields: - type: array - items: - $ref: '#/definitions/contactdb_custom_field_with_id' - required: - - custom_fields - examples: - application/json: - custom_fields: - - id: 6234 - name: age - type: number - - id: 6233 - name: country - type: text - - id: 6235 - name: favorite_color - type: text - - id: 6239 - name: fname - type: text - - id: 6240 - name: lname - type: text - - id: 49439 - name: pet - type: text - '401': + $ref: '#/definitions/whitelabel::domain' + security: + - Authorization: [] + delete: + summary: Delete a domain whitelabel. + description: |- + **This endpoint allows you to delete a domain whitelabel.** + + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: DELETE_whitelabel-domains-domain_id + consumes: + - application/json + produces: [] + parameters: + - name: body + in: body + schema: + type: 'null' + responses: + '204': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + type: object security: - Authorization: [] - post: - summary: Create a Custom Field + patch: + summary: Update a domain whitelabel. description: |- - **This endpoint allows you to create a custom field.** + **This endpoint allows you to update the settings for a domain whitelabel.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: POST_contactdb-custom_fields + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: PATCH_whitelabel-domains-domain_id consumes: - application/json produces: @@ -3605,109 +2500,132 @@ paths: schema: type: object properties: - name: - type: string - type: - type: string + default: + type: boolean + default: false + description: Indicates whether this domain whitelabel should be considered the default. + custom_spf: + type: boolean + default: false + description: Indicates whether to generate a custom SPF record for manual security. example: - name: pet - type: text + default: false + custom_spf: true responses: - '201': + '200': description: '' schema: + title: Update a Domain response type: object properties: - id: - type: integer - name: - type: string - type: - type: string - examples: - application/json: - id: 1 - name: pet - type: text - '400': - description: |- - "" : "Returned if request body is invalid JSON" - "type" : "Returned if custom field type is invalid or not provided" - "name" : "Returned if custom field name is not provided" - schema: - type: object - examples: - application/json: - errors: - - field: null - message: Returned if request body is invalid JSON - - field: type - message: Returned if custom field type is invalid or not provided - - field: name - message: Returned if custom field name is not provided + default false: + description: Inidcates whether this domain whitelabel should be considered the default. Defaults to false. + type: boolean + custom_spf false: + description: Indicates whether to generate a custom SPF record for manual security. Defaults to false. + type: boolean security: - Authorization: [] - '/contactdb/custom_fields/{custom_field_id}': + '/templates/{template_id}': parameters: - - name: custom_field_id + - name: template_id in: path + description: The id of the transactional template you want to delete. required: true type: string delete: - summary: Delete a Custom Field - description: |- - **This endpoint allows you to delete a custom field by ID.** + summary: Delete a template. + description: | + **This endpoint allows you to delete a transactional template.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: DELETE_contactdb-custom_fields-custom_field_id + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: DELETE_templates-template_id + consumes: + - application/json + produces: [] + parameters: + - name: body + in: body + schema: + type: 'null' + responses: + '204': + description: '' + schema: + type: object + security: + - Authorization: [] + get: + summary: Retrieve a single transactional template. + description: | + **This endpoint allows you to retrieve a single transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: GET_templates-template_id consumes: - application/json produces: - application/json parameters: [] responses: - '202': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - message: Custom Field delete is processing. - '400': - description: '"id" : "Returned if custom_field_id is not valid"' + $ref: '#/definitions/transactional_template' + security: + - Authorization: [] + patch: + summary: Edit a transactional template. + description: | + **This endpoint allows you to edit a transactional template.** + + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: PATCH_templates-template_id + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: Custom field in use by one or more segment conditions - - message: Custom field ID does not exist - '401': + type: object + properties: + name: + type: string + description: The name of the transactional template. + maxLength: 100 + example: + name: new_example_name + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"custom_field_id" : "Returned if custom_field_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/transactional_template' examples: application/json: - errors: - - message: Custom field ID does not exist + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: new_example_name + versions: [] security: - Authorization: [] + /mail_settings/bcc: + parameters: [] get: - summary: Retrieve a Custom Field + summary: Retrieve all BCC mail settings description: |- - **This endpoint allows you to retrieve a custom field by ID.** + **This endpoint allows you to retrieve your current BCC mail settings.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: GET_contactdb-custom_fields-custom_field_id + When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. + + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-bcc consumes: - application/json produces: @@ -3717,84 +2635,69 @@ paths: '200': description: '' schema: - $ref: '#/definitions/contactdb_custom_field_with_id' + $ref: '#/definitions/mail_settings_bcc' examples: application/json: - id: 1 - name: pet - type: text - '400': - description: '' + email: example@example.com + enabled: false + security: + - Authorization: [] + patch: + summary: 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). + operationId: PATCH_mail_settings-bcc + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: invalid id - '401': + $ref: '#/definitions/mail_settings_patch' + example: + enabled: false + email: email@example.com + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"custom_field_id" : "Returned if custom_field_id does not exist"' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_patch' examples: application/json: - errors: - - message: Custom field ID does not exist + email: example@example.com + enabled: false security: - Authorization: [] - '/api_keys/{api_key_id}': - parameters: - - name: api_key_id - in: path - required: true - type: string - patch: - summary: Update API keys - description: |- - **This endpoint allows you to update the name of an existing API Key.** - - A JSON request body with a "name" property is required. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + /contactdb/recipients/billable_count: + parameters: [] + get: + summary: Retrieve the count of billable recipients + description: |- + **This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.** - ## URI Parameters + You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are updating.| - operationId: PATCH_api_keys-api_key_id + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: GET_contactdb-recipients-billable_count consumes: - application/json produces: - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - name: - type: string - description: The new name of the API Key. - example: - name: A New Hope + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/api_key_name_id' + $ref: '#/definitions/contactdb_recipient_count' examples: application/json: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope + recipient_count: 1234 '401': description: '' schema: @@ -3806,13 +2709,17 @@ paths: message: authorization required security: - Authorization: [] + /partner_settings/new_relic: + parameters: [] get: - summary: Retrieve an existing API Key + summary: Returns all New Relic partner settings. description: |- - **This endpoint allows you to retrieve a single api key.** + **This endpoint allows you to retrieve your current New Relic partner settings.** - If the API Key ID does not exist an HTTP 404 will be returned. - operationId: GET_api_keys-api_key_id + Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). + + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). + operationId: GET_partner_settings-new_relic consumes: - application/json produces: @@ -3822,49 +2729,23 @@ paths: '200': description: '' schema: - type: object - properties: - result: - type: array - items: - $ref: '#/definitions/api_key_name_id_scopes' - examples: - application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: Unexpected error in API call. See HTTP response body for details. - schema: - type: object + $ref: '#/definitions/partner_settings_new_relic' examples: application/json: - errors: - - field: null - message: unable to find API Key + enable_subuser_statistics: false + enabled: true + license_key: '' security: - Authorization: [] - put: - summary: Update the name & scopes of an API Key - description: | - **This endpoint allows you to update the name and scopes of a given API key.** + patch: + summary: Updates New Relic partner settings. + description: |- + **This endpoint allows you to update or change your New Relic partner settings.** - A JSON request body with a "name" property is required. - Most provide the list of all the scopes an api key should have. + 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). - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - operationId: PUT_api_keys-api_key_id + By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). + operationId: PATCH_partner_settings-new_relic consumes: - application/json produces: @@ -3875,102 +2756,73 @@ paths: schema: type: object properties: - name: + license_key: type: string - scopes: - type: array - items: - type: string + description: The license key for your New Relic account. + enabled: + type: boolean + description: Indicates if this partner setting is enabled. + enable_subuser_statistics: + type: boolean + description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. example: - name: A New Hope - scopes: - - user.profile.read - - user.profile.update + license_key: '' + enabled: true + enable_subuser_statistics: true responses: '200': description: '' schema: - $ref: '#/definitions/api_key_name_id_scopes' - examples: - application/json: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - scopes: - - user.profile.read - - user.profile.update - '400': - description: Unexpected error in API call. See HTTP response body for details. - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: expected JSON request body with 'name' property - '401': - description: '' - schema: - type: object - '404': - description: Unexpected error in API call. See HTTP response body for details. - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/partner_settings_new_relic' examples: application/json: - errors: - - field: null - message: unable to find API Key to update + enable_subuser_statistics: true + enabled: true + license_key: '' security: - Authorization: [] - delete: - summary: Delete API keys + '/asm/groups/{group_id}/suppressions': + parameters: + - name: group_id + in: path + description: The id of the suppression group that you are retrieving email addresses from. + required: true + type: string + get: + summary: Retrieve all suppressions for a suppression group description: |- - **This endpoint allows you to revoke an existing API Key** - - Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. - - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - - ## URI Parameters + **This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.** - | URI Parameter | Type | Required? | Description | - |---|---|---|---| - |api_key_id |string | required | The ID of the API Key you are deleting.| - operationId: DELETE_api_keys-api_key_id + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: GET_asm-groups-group_id-suppressions consumes: - application/json produces: - application/json parameters: [] responses: - '204': - description: '' - schema: - type: 'null' - '404': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + description: The list of email addresses belonging to the given suppression group. + items: + type: string examples: application/json: - errors: - - field: null - message: unable to find API Key + - example@example.com + - example2@example.com security: - Authorization: [] - '/user/scheduled_sends/{batch_id}': - parameters: - - name: batch_id - in: path - required: true - type: string - patch: - summary: Update user scheduled send information + post: + summary: Add suppressions to a suppression group description: |- - **This endpoint allows you to update the status of a scheduled send for the given `batch_id`.** + **This endpoint allows you to add email addresses to an unsubscribe group.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: PATCH_user-scheduled_sends-batch_id + If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list. + + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: POST_asm-groups-group_id-suppressions consumes: - application/json produces: @@ -3981,61 +2833,59 @@ paths: schema: type: object properties: - status: - type: string - description: The status you would like the scheduled send to have. - enum: - - cancel - - pause + recipient_emails: + type: array + description: The email address that you want to add to the unsubscribe group. + items: + type: string required: - - status + - recipient_emails example: - status: pause + recipient_emails: + - test1@example.com + - test2@example.com responses: - '204': - description: '' - schema: - type: 'null' - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: status - message: status must be either cancel or pause - '401': + '201': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"" : "batch id not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + recipient_emails: + type: array + description: The email address that were added to the suppressions list. + items: + type: string + required: + - recipient_emails examples: application/json: - errors: - - field: null - message: batch id not found + recipient_emails: + - test1@example.com + - test2@example.com security: - Authorization: [] + '/asm/groups/{group_id}/suppressions/{email}': + parameters: + - name: group_id + in: path + description: The id of the suppression group that you are removing an email address from. + required: true + type: string + - name: email + in: path + description: The email address that you want to remove from the suppression group. + required: true + type: string delete: - summary: Delete a cancellation or pause of a scheduled send + summary: Delete a suppression from a suppression group description: |- - **This endpoint allows you to delete the cancellation/pause of a scheduled send.** + **This endpoint allows you to remove a suppressed email address from the given suppression group.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: DELETE_user-scheduled_sends-batch_id + Suppressions are recipient email addresses that are added to [unsubscribe groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html). Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + operationId: DELETE_asm-groups-group_id-suppressions-email consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body @@ -4046,33 +2896,21 @@ paths: description: '' schema: type: 'null' - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: batch id not found security: - Authorization: [] + /templates: + parameters: [] get: - summary: Retrieve scheduled send + tags: + - Transactional Templates + summary: Retrieve all transactional templates. description: |- - **This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.** + **This endpoint allows you to retrieve all transactional templates.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: GET_user-scheduled_sends-batch_id + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: GET_templates consumes: - application/json produces: @@ -4083,38 +2921,21 @@ paths: description: '' schema: type: array - title: Retrieve scheduled send response items: - $ref: '#/definitions/user_scheduled_send_status' - examples: - application/json: - - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi - status: cancel - - batch_id: IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg - status: pause - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + $ref: '#/definitions/transactional_template' security: - Authorization: [] - /user/scheduled_sends: - parameters: [] post: - summary: Cancel or pause a scheduled send + tags: + - Transactional Templates + summary: Create a transactional template. description: |- - **This endpoint allows you to cancel or pause an email that has been scheduled to be sent.** + **This endpoint allows you to create a transactional template.** - If the maximum number of cancellations/pauses are added, HTTP 400 will - be returned. + Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: POST_user-scheduled_sends + Transactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + operationId: POST_templates consumes: - application/json produces: @@ -4123,65 +2944,86 @@ paths: - name: body in: body schema: - title: Cancel or pause a scheduled send request type: object properties: - batch_id: - type: string - description: The batch ID is the identifier that your scheduled mail sends share. - pattern: '^[a-zA-Z0-9]' - status: + name: type: string - default: pause - description: 'The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}' - enum: - - pause - - cancel + description: The name for the new transactional template. + maxLength: 100 required: - - batch_id - - status + - name example: - batch_id: YOUR_BATCH_ID - status: pause + name: example_name responses: '201': description: '' schema: - $ref: '#/definitions/user_scheduled_send_status' - '400': - description: |- - "" : "max limit reached" - "batch_id" : "invalid batch id" - "batch_id" : "a status for this batch id exists, try PATCH to update the status" - schema: - type: object + $ref: '#/definitions/transactional_template' examples: application/json: - errors: - - field: null - message: max limit reached - - field: batch_id - message: invalid batch id - - field: batch_id - message: 'a status for this batch id exists, try PATCH to update the status' - '401': - description: '' + id: 733ba07f-ead1-41fc-933a-3976baa23716 + name: example_name + versions: [] + security: + - Authorization: [] + /ips/pools: + parameters: [] + post: + tags: + - IP Pools + summary: 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. + operationId: POST_ips-pools + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body schema: type: object + properties: + name: + type: string + description: The name of your new IP pool. + maxLength: 64 + required: + - name + example: + name: marketing + responses: + '200': + description: '' + schema: + $ref: '#/definitions/ip_pool' examples: application/json: - errors: - - field: null - message: authorization required + name: marketing security: - Authorization: [] get: - summary: Retrieve all scheduled sends + tags: + - IP Pools + summary: Retrieve all IP pools. description: |- - **This endpoint allows you to retrieve all cancel/paused scheduled send information.** + **This endpoint allows you to retreive all of your IP pools.** - The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - operationId: GET_user-scheduled_sends + 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. + operationId: GET_ips-pools consumes: - application/json produces: @@ -4193,71 +3035,50 @@ paths: schema: type: array items: - $ref: '#/definitions/user_scheduled_send_status' - examples: - application/json: - - batch_id: YzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYg - status: cancel - - batch_id: UtNTI1NDAwNmQzZmYzLTVlM2NhNWIwYgYzJlNTkxMmEtOWM3Ny0xMWU1LTkwM2 - status: cancel - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/ip_pool' examples: application/json: - errors: - - field: null - message: authorization required + - name: marketing + - name: transactional security: - Authorization: [] - '/subusers/{subuser_name}': - parameters: - - name: subuser_name - in: path - required: true - type: string - delete: - summary: Delete a subuser + /mail_settings/spam_check: + parameters: [] + get: + summary: Retrieve spam check mail settings description: |- - This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. + **This endpoint allows you to retrieve your current Spam Checker mail settings.** - For more information about Subusers: + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - operationId: DELETE_subusers-subuser_name + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings-spam_check consumes: - application/json produces: - application/json parameters: [] responses: - '204': - description: '' - schema: - type: object - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_spam_check' examples: application/json: - errors: - - field: null - message: authorization required + enabled: false + max_score: 6 + url: 'http://example.com' security: - Authorization: [] patch: - summary: Enable/disable a subuser + summary: Update spam check mail settings description: |- - This endpoint allows you to enable or disable a subuser. + **This endpoint allows you to update your current spam checker mail settings.** - For more information about Subusers: + The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - operationId: PATCH_subusers-subuser_name + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: PATCH_mail_settings-spam_check consumes: - application/json produces: @@ -4268,55 +3089,45 @@ paths: schema: type: object properties: - disabled: + enabled: type: boolean - description: 'Whether or not this subuser is disabled. True means disabled, False means enabled.' + description: Indicates if you want the spam check mail setting to be enabled or not. + url: + type: string + description: The Inbound Parse URL where you would like your spam reports to be sent to. + max_score: + type: integer + default: 5 + description: 'The new max score, or spam threshold that you would like to set for the spam checker.' + minimum: 1 + maximum: 10 example: - disabled: false + enabled: true + url: url + max_score: 5 responses: - '204': - description: '' - schema: - type: object - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: invalid username - - message: no fields provided - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '500': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/mail_settings_spam_check' examples: application/json: - errors: - - message: unable to enable user + enabled: false + max_score: 6 + url: 'http://example.com' security: - Authorization: [] - /mail_settings/plain_content: + /tracking_settings/click: parameters: [] get: - summary: Retrieve plain content mail settings + summary: Retrieve Click Track Settings description: |- - **This endpoint allows you to retrieve your current Plain Content mail settings.** + **This endpoint allows you to retrieve your current click tracking setting.** - The plain content setting will automatically convert any plain text emails that you send to HTML before sending. + 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. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-plain_content + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-click consumes: - application/json produces: @@ -4328,23 +3139,30 @@ paths: 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 the Plain Content mail setting is enabled. + description: Indicates if click tracking is enabled or disabled. + required: + - enable_text + - enabled examples: application/json: - enabled: false + enable_text: false + enabled: true security: - Authorization: [] patch: - summary: Update plain content mail settings + summary: Update Click Tracking Settings description: |- - **This endpoint allows you to update your current Plain Content mail settings.** + **This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** - The plain content setting will automatically convert any plain text emails that you send to HTML before sending. + 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. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-plain_content + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-click consumes: - application/json produces: @@ -4357,702 +3175,1070 @@ paths: properties: enabled: type: boolean - description: The new setting you would like to use for your Plain Content mail setting. + description: The setting you want to use for click tracking. example: - enabled: false + enabled: true responses: '200': description: '' schema: type: object properties: + enable_text: + type: boolean + description: Indicates if click tracking is enabled for plain text emails enabled: type: boolean - description: Indicates if your Plain Content mail setting is enabled. + description: The new setting new setting for click tracking. + required: + - enable_text + - enabled examples: application/json: - enabled: false + enable_text: false + enabled: true security: - Authorization: [] - '/campaigns/{campaign_id}/schedules': - parameters: - - name: campaign_id - in: path - required: true - type: integer - get: - summary: View Scheduled Time of a Campaign + /whitelabel/links: + parameters: [] + post: + tags: + - Whitelabel - Links + summary: Create a Link Whitelabel description: |- - **This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent.** + **This endpoint allows you to create a new link whitelabel.** - For more information: + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: GET_campaigns-campaign_id-schedules + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: POST_whitelabel-links consumes: - application/json produces: - application/json - parameters: [] - responses: - '200': - description: '' + parameters: + - name: limit + in: query + description: Number of domains to return. + type: integer + default: 50 + - name: offset + in: query + description: Paging offset. + type: integer + default: 0 + - name: body + in: body schema: - title: View Scheduled Time of a Campaign response type: object properties: - send_at: - type: integer - format: int64 + domain: + type: string + description: The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address. + subdomain: + type: string + description: The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel. + default: + type: boolean + description: 'Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.' + enum: + - true + - false required: - - send_at + - domain + - subdomain + example: + domain: example.com + subdomain: mail + default: true + responses: + '201': + description: '' + schema: + $ref: '#/definitions/link_whitelabel' examples: application/json: - send_at: 1490778528 - '404': - description: '"": "not found"' + id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: false + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + security: + - Authorization: [] + get: + tags: + - Whitelabel - Links + summary: Retrieve all link whitelabels + description: |- + **This endpoint allows you to retrieve all link whitelabels.** + + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: GET_whitelabel-links + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: Limits the number of results returned per page. + type: integer + responses: + '200': + description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + $ref: '#/definitions/link_whitelabel' examples: application/json: - errors: - - field: null - message: not found + - id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + default: true + valid: true + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: mail.example.com + data: sendgrid.net + owner_cname: + valid: true + type: cname + host: 7.example.com + data: sendgrid.net + - id: 2 + domain: example2.com + subdomain: news + username: john@example.com + user_id: 8 + default: false + valid: false + legacy: false + dns: + domain_cname: + valid: true + type: cname + host: news.example2.com + data: sendgrid.net + owner_cname: + valid: false + type: cname + host: 8.example2.com + data: sendgrid.net security: - Authorization: [] - patch: - summary: Update a Scheduled Campaign + '/asm/suppressions/global/{email}': + parameters: + - name: email + in: path + description: The email address you want to remove from the global suppressions group. + required: true + type: string + delete: + tags: + - Suppression Management - Global Suppressions + summary: Delete a Global Suppression description: |- - **This endpoint allows to you change the scheduled time and date for a campaign to be sent.** - - For more information: + **This endpoint allows you to remove an email address from the global suppressions group.** - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: PATCH_campaigns-campaign_id-schedules + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: DELETE_asm-suppressions-global-email consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: - title: Update a Scheduled Campaign request - type: object - properties: - send_at: - type: integer - format: int64 - required: - - send_at - example: - send_at: 1489451436 + type: 'null' responses: - '200': + '204': description: '' schema: - title: Update a Scheduled Campaign response type: object - properties: - id: - type: integer - description: The campaign ID - send_at: - type: integer - description: The unix timestamp to send the campaign. - status: - type: string - description: The status of the schedule. - required: - - id - - send_at - - status - '400': - description: |- - "": "The JSON you have submitted cannot be parsed." - "send_at": "Please choose a future time for sending your campaign." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: send_at - message: Please choose a future time for sending your campaign. - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing' - '403': - description: '"send_at": "You cannot update the send_at value of non-scheduled campaign."' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: send_at - message: You cannot update the send_at value of non-scheduled campaign. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found security: - Authorization: [] - delete: - summary: Unschedule a Scheduled Campaign + get: + tags: + - Suppression Management - Global Suppressions + summary: Retrieve a Global Suppression description: |- - **This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.** - - A successful unschedule will return a 204. - If the specified campaign is in the process of being sent, the only option is to cancel (a different method). + **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.** - For more information: + If the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: DELETE_campaigns-campaign_id-schedules + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: GET_asm-suppressions-global-email consumes: - application/json produces: - application/json parameters: [] responses: - '204': + '200': description: '' schema: - type: 'null' - '403': - description: |- - "": "This campaign is already In Progress." - "": "This campaign is already Sent." - "": "This campaign is already Paused." - "": "This campaign is already Canceled." - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: This campaign is already In Progress. - - field: null - message: This campaign is already Sent. - - field: null - message: This campaign is already Paused. - - field: null - message: This campaign is already Canceled. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + title: Retrieve a Global Suppression response + type: object + properties: + recipient_email: + type: string + description: The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed. + required: + - recipient_email security: - Authorization: [] - post: - summary: Schedule a Campaign + /scopes: + parameters: [] + get: + tags: + - API Key Permissions + summary: Retrieve a list of scopes for which this user has access. description: |- - **This endpoint allows you to schedule a specific date and time for your campaign to be sent.** - - For more information: + **This endpoint returns a list of all scopes that this user has access to.** - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: POST_campaigns-campaign_id-schedules + 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). + operationId: GET_scopes consumes: - application/json produces: - application/json - parameters: - - name: body - in: body - schema: - title: Schedule a Campaign request - type: object - properties: - send_at: - type: integer - description: The unix timestamp for the date and time you would like your campaign to be sent out. - required: - - send_at - example: - send_at: 1489771528 + parameters: [] responses: - '201': + '200': description: '' schema: - title: Schedule a Campaign response type: object properties: - id: - type: integer - description: The campaign ID. - send_at: - type: integer - description: The date time you scheduled your campaign to be sent. - status: - type: string - description: The status of your campaign. - enum: - - Scheduled + scopes: + type: array + description: The list of scopes for which this user has access. + uniqueItems: true + items: + type: string required: - - id - - send_at - - status - examples: - application/json: - id: 1234 - send_at: 1489771528 - status: Scheduled - '400': - description: |- - "subject": "subject can't be blank" - "sender_id": "sender_id can't be blank" - "plain_content": "plain_content can't be blank, please provide plain text or html content" - "list_ids": "You must select at least 1 segment or 1 list to send to." - "send_at": "Please choose a future time for sending your campaign." - "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." - "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." - "": "The JSON you have submitted cannot be parsed." - "":"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" - schema: - $ref: '#/definitions/global:ErrorResponse' + - scopes examples: application/json: - errors: - - field: subject - message: subject can't be blank - - field: sender_id - message: sender_id can't be blank - - field: plain_content - message: 'plain_content can''t be blank, please provide plain text or html content' - - field: list_id - message: You must select at least 1 segment or 1 list to send to. - - field: unsubscribe_tag - message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' - - field: suppression_group_id - message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + scopes: + - mail.send + - alerts.create + - alerts.read '401': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '"": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH."' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: + type: object + properties: errors: - - field: null - message: You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + description: This 401 response indicates that the user making the call doesn't have the authorization to view the list of scopes. + items: + type: object + properties: + field: + type: 'null' + description: This empty field is returned instead of the list of scopes if the user making the call doesn't have the authorization required. + message: + type: string + description: Explains why the scopes cannot be returned. + required: + - message + required: + - errors examples: application/json: errors: - field: null - message: not found + message: authorization required security: - Authorization: [] - /mail_settings/template: + /asm/groups: parameters: [] - get: - summary: Retrieve legacy template mail settings + post: + tags: + - Suppression Management - Unsubscribe Groups + summary: Create a new suppression group description: |- - **This endpoint allows you to retrieve your current legacy email template settings.** + **This endpoint allows you to create a new suppression group.** - 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). + Suppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - The 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. + The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-template + Each user can create up to 25 different suppression groups. + operationId: POST_asm-groups consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name that you would like to use for your new suppression group. + maxLength: 30 + description: + type: string + description: A brief description of your new suppression group. + maxLength: 100 + is_default: + type: boolean + description: Indicates if you would like this to be your default suppression group. + required: + - name + - description + example: + name: Product Suggestions + description: Suggestions for products our users might like. + is_default: true responses: - '200': + '201': description: '' schema: - $ref: '#/definitions/mail_settings_template' + type: object + properties: + id: + type: integer + description: The ID of the suppression group. + name: + type: string + description: The name of the suppression group. + description: + type: string + description: A brief description of the suppression group. + is_default: + type: boolean + description: Indicates if this is the default suppression group. + required: + - id + - name + - description + - is_default examples: application/json: - enabled: false - html_content: | -<% body %>Example
+ id: 103 + name: Product Suggestions + description: Suggestions for products our users might like. + is_default: false security: - Authorization: [] - patch: - summary: Update template mail settings + get: + tags: + - Suppression Management - Unsubscribe Groups + summary: Retrieve information about multiple suppression groups description: |- - **This endpoint allows you to update your current legacy email template settings.** + **This endpoint allows you to retrieve information about multiple suppression groups.** - 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). + This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID. + operationId: GET_asm-groups + consumes: + - application/json + produces: + - application/json + parameters: + - name: id + in: query + description: The ID of a suppression group that you want to retrieve information for. + type: integer + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/suppression_group' + examples: + application/json: + - id: 100 + name: Newsletters + description: Our monthly newsletter. + last_email_sent_at: null + is_default: true + unsubscribes: 400 + - id: 101 + name: Alerts + description: Emails triggered by user-defined rules. + last_email_sent_at: null + is_default: false + unsubscribes: 1 + security: + - Authorization: [] + /user/webhooks/parse/stats: + parameters: [] + get: + tags: + - Stats - Parse Webhook Stats + summary: Retrieves Inbound Parse Webhook statistics. + description: |- + **This endpoint allows you to retrieve the statistics for your Parse Webhook useage.** - 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. + SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incomming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-template + There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the [Library Index](https://sendgrid.com/docs/Integrate/libraries.html#-Webhook-Libraries). + operationId: GET_user-webhooks-parse-stats consumes: - application/json produces: - application/json parameters: - - name: body - in: body - schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if you want to enable the legacy email template mail setting. - html_content: - type: string - description: The new HTML content for your legacy email template. - example: - enabled: true - html_content: <% body %> + - name: limit + in: query + description: The number of statistics to return on each page. + required: false + type: string + - name: offset + in: query + description: The number of statistics to skip. + required: false + type: string + - name: aggregated_by + in: query + description: 'How you would like the statistics to by grouped. ' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics you want to retrieve. Must be in the format YYYY-MM-DD + required: false + type: string + default: The day the request is made. responses: '200': description: '' schema: - type: object - properties: - enabled: - type: boolean - html_content: - type: string + type: array + items: + type: object + properties: + date: + type: string + description: The date that the stats were collected. + stats: + type: array + description: The Parse Webhook usage statistics. + items: + type: object + properties: + metrics: + type: object + properties: + received: + type: number + description: The number of emails received and parsed by the Parse Webhook. + required: + - received + required: + - date + - stats examples: application/json: - enabled: false - html_content: | -<% body %>Example
+ - date: '2015-10-11' + stats: + - metrics: + received: 0 + - date: '2015-10-12' + stats: + - metrics: + received: 0 + - date: '2015-10-13' + stats: + - metrics: + received: 0 + - date: '2015-10-14' + stats: + - metrics: + received: 0 + - date: '2015-10-15' + stats: + - metrics: + received: 0 + - date: '2015-10-16' + stats: + - metrics: + received: 0 + - date: '2015-10-17' + stats: + - metrics: + received: 0 + - date: '2015-10-18' + stats: + - metrics: + received: 0 + - date: '2015-10-19' + stats: + - metrics: + received: 0 + - date: '2015-10-20' + stats: + - metrics: + received: 0 + - date: '2015-10-21' + stats: + - metrics: + received: 0 + - date: '2015-10-22' + stats: + - metrics: + received: 0 + - date: '2015-10-23' + stats: + - metrics: + received: 0 + - date: '2015-10-24' + stats: + - metrics: + received: 0 + - date: '2015-10-25' + stats: + - metrics: + received: 0 + - date: '2015-10-26' + stats: + - metrics: + received: 0 + - date: '2015-10-27' + stats: + - metrics: + received: 0 + - date: '2015-10-28' + stats: + - metrics: + received: 0 + - date: '2015-10-29' + stats: + - metrics: + received: 0 + - date: '2015-10-30' + stats: + - metrics: + received: 0 + - date: '2015-10-31' + stats: + - metrics: + received: 0 + - date: '2015-11-01' + stats: + - metrics: + received: 0 + - date: '2015-11-02' + stats: + - metrics: + received: 0 + - date: '2015-11-03' + stats: + - metrics: + received: 0 + - date: '2015-11-04' + stats: + - metrics: + received: 0 + - date: '2015-11-05' + stats: + - metrics: + received: 0 + - date: '2015-11-06' + stats: + - metrics: + received: 0 + - date: '2015-11-07' + stats: + - metrics: + received: 0 + - date: '2015-11-08' + stats: + - metrics: + received: 0 + - date: '2015-11-09' + stats: + - metrics: + received: 0 + - date: '2015-11-10' + stats: + - metrics: + received: 0 security: - Authorization: [] - /mail_settings/address_whitelist: + /subusers/stats/sums: parameters: [] get: - summary: Retrieve address whitelist mail settings + tags: + - Stats - Subuser Stats + summary: ' Retrieve the totals for each email statistic metric for all subusers.' description: |- - **This endpoint allows you to retrieve your current email address whitelist settings.** - - The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain “example.com,” and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + **This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-address_whitelist - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_address_whitelabel' - examples: - application/json: - enabled: false - list: - - example.com - security: - - Authorization: [] - patch: - summary: 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. + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-address_whitelist + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: GET_subusers-stats-sums consumes: - application/json produces: - application/json parameters: - - name: body - in: body - schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if your email address whitelist is enabled. - list: - type: array - description: 'Either a single email address that you want whitelisted or a domain, for which all email addresses belonging to this domain will be whitelisted.' - items: - type: string - example: - enabled: true - list: - - email1@example.com - - example.com + - name: sort_by_direction + in: query + description: 'The direction you want to sort. ' + required: false + type: string + default: desc + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: limit + in: query + description: Limits the number of results returned per page. + required: false + type: integer + default: 5 + - name: offset + in: query + description: The point in the list to begin retrieving results from. + required: false + type: integer + default: 0 + - name: aggregated_by + in: query + description: How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string + default: delivered responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_address_whitelabel' + $ref: '#/definitions/category_stats' examples: application/json: - enabled: true - list: - - email1@example.com + date: '2015-10-11' + stats: [] security: - Authorization: [] - /mail_settings/footer: + /subusers/stats: parameters: [] get: - summary: 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). - operationId: GET_mail_settings-footer - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_footer' - examples: - application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content - security: - - Authorization: [] - patch: - summary: 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). - operationId: PATCH_mail_settings-footer - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_footer' - example: - enabled: true - html_content: ... - plain_content: ... - responses: - '200': - description: '' - schema: - $ref: '#/definitions/mail_settings_footer' - examples: - application/json: - enabled: true - html_content: Example HTML content - plain_content: Example plain content - security: - - Authorization: [] - /partner_settings/new_relic: - parameters: [] - patch: - summary: Updates New Relic partner settings. + tags: + - Stats - Subuser Stats + summary: Retrieve email statistics for your subusers. description: |- - **This endpoint allows you to update or change your New Relic partner settings.** - - Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). - - By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). - operationId: PATCH_partner_settings-new_relic - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - license_key: - type: string - description: The license key for your New Relic account. - enabled: - type: boolean - description: Indicates if this partner setting is enabled. - enable_subuser_statistics: - type: boolean - description: Indicates if your subuser statistics will be sent to your New Relic Dashboard. - example: - license_key: '' - enabled: true - enable_subuser_statistics: true + **This endpoint allows you to retrieve the email statistics for the given subusers.** + + You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser. + + While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + + For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + operationId: GET_subusers-stats + consumes: + - application/json + produces: + - application/json + parameters: + - name: limit + in: query + description: Limits the number of results returned per page. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results from. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: subusers + in: query + description: The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers. + required: true + type: string + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string responses: '200': description: '' schema: - $ref: '#/definitions/partner_settings_new_relic' + $ref: '#/definitions/stats' examples: application/json: - enable_subuser_statistics: true - enabled: true - license_key: '' + - date: '2015-10-01' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-02' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-03' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-04' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-05' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-06' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-07' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-08' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-09' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-10-10' + stats: + - type: subuser + name: Matt_subuser + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 security: - Authorization: [] - get: - summary: Returns all New Relic partner settings. + /api_keys: + parameters: [] + post: + summary: Create API keys description: |- - **This endpoint allows you to retrieve your current New Relic partner settings.** + **This enpoint allows you to create a new random API Key for the user.** - 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). + A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. - By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). - operationId: GET_partner_settings-new_relic - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/partner_settings_new_relic' - examples: - application/json: - enable_subuser_statistics: false - enabled: true - license_key: '' - security: - - Authorization: [] - /partner_settings: - parameters: [] - get: - summary: Returns a list of all partner settings. - description: |- - **This endpoint allows you to retrieve a list of all partner settings that you can enable.** + There is a limit of 100 API Keys on your account. - Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). - operationId: GET_partner_settings + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. + operationId: create-api-keys consumes: - application/json produces: - application/json parameters: - - name: limit - in: query - description: The number of settings to return per page. - type: integer - - name: offset - in: query - description: The paging offset. - type: integer + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The name you will use to describe this API Key. + scopes: + type: array + description: The individual permissions that you are giving to this API Key. + items: + type: string + required: + - name + example: + name: My API Key + scopes: + - mail.send + - alerts.create + - alerts.read responses: - '200': + '201': description: '' schema: type: object properties: - result: + api_key: + type: string + api_key_id: + type: string + name: + type: string + scopes: 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 + type: string examples: application/json: - result: - - title: Partner title - enabled: true - name: partner_name - description: A description of a partner. - security: - - Authorization: [] - /mail_settings/forward_spam: - parameters: [] - patch: - summary: 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). - operationId: PATCH_mail_settings-forward_spam - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body + api_key: SG.xxxxxxxx.yyyyyyyy + api_key_id: xxxxxxxx + name: My API Key + scopes: + - mail.send + - alerts.create + - alerts.read + '400': + description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' - example: - email: '' - enabled: false - responses: - '200': + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: name + message: missing required argument + '401': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - email: '' - enabled: false + errors: + - field: null + message: authorization required + '403': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: Cannot create more than 100 API Keys security: - Authorization: [] get: - summary: Retrieve forward spam mail settings + summary: Retrieve all API Keys belonging to the authenticated user 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. + **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-forward_spam + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + operationId: GET_api_keys consumes: - application/json produces: @@ -5062,358 +4248,646 @@ paths: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_spam' + type: object + properties: + result: + type: array + items: + $ref: '#/definitions/api_key_name_id' examples: application/json: - email: '' - enabled: true - security: - - Authorization: [] - /mail_settings/forward_bounce: - parameters: [] - patch: - summary: 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). - operationId: PATCH_mail_settings-forward_bounce - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/mail_settings_forward_bounce' - example: - enabled: true - email: example@example.com - responses: - '200': + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id + '401': description: '' schema: - $ref: '#/definitions/mail_settings_forward_bounce' + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - email: '' - enabled: true + errors: + - field: null + message: authorization required security: - Authorization: [] + /categories/stats: + parameters: [] get: - summary: Retrieve forward bounce mail settings + tags: + - Stats - Category Stats + summary: Retrieve Email Statistics for Categories description: |- - **This endpoint allows you to retrieve your current bounce forwarding mail settings.** + **This endpoint allows you to retrieve all of your email statistics for each of your categories.** - Activating this setting allows you to specify an email address to which bounce reports are forwarded. + If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-forward_bounce + 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). + operationId: GET_categories-stats consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: categories + in: query + description: The individual categories that you want to retrieve statistics for. You may include up to 10 different categories. + required: true + type: string + - name: limit + in: query + description: The number of results to include. + required: false + type: integer + default: 500 + maximum: 500 + - name: offset + in: query + description: The number of results to skip. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_forward_bounce' + type: array + items: + $ref: '#/definitions/category_stats' examples: application/json: - enabled: false - email: null + - date: '2015-10-01' + stats: + - type: category + name: docs + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - type: category + name: mattscategory + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-01' + stats: + - type: category + name: docs + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - type: category + name: mattscategory + metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 security: - Authorization: [] - /user/account: + /stats: parameters: [] get: tags: - - Users API - summary: Get a user's account information. + - Stats - Global Stats + summary: Retrieve global email statistics description: |- - **This endpoint allows you to retrieve your user account details.** - - Your user's account information includes the user's account type and reputation. - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: + **This endpoint allows you to retrieve all of your global email statistics between a given date range.** - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: GET_user-account + Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats. + operationId: GET_stats consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: limit + in: query + description: The number of results to return. + required: false + type: integer + - name: offset + in: query + description: The point in the list to begin retrieving results. + required: false + type: integer + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string responses: '200': description: '' schema: - title: GET User Account response - type: object - properties: - type: - type: string - description: The type of account for this user. - enum: - - free - - paid - reputation: - type: number - description: The sender reputation for this user. - required: - - type - - reputation + type: array + items: + type: object + properties: + date: + type: string + description: The date the stats were gathered. + stats: + type: array + description: The individual email activity stats. + items: + type: object + properties: + metrics: + type: object + properties: + blocks: + type: integer + description: The number of emails that were not allowed to be delivered by ISPs. + bounce_drops: + type: integer + description: The number of emails that were dropped because of a bounce. + bounces: + type: integer + description: The number of emails that bounced instead of being delivered. + clicks: + type: integer + description: The number of links that were clicked in your emails. + deferred: + type: integer + description: 'The number of emails that temporarily could not be delivered. ' + delivered: + type: integer + description: The number of emails SendGrid was able to confirm were actually delivered to a recipient. + invalid_emails: + type: integer + description: The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid. + opens: + type: integer + description: The total number of times your emails were opened by recipients. + processed: + type: integer + description: 'Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed.' + requests: + type: integer + description: The number of emails that were requested to be delivered. + spam_report_drops: + type: integer + description: The number of emails that were dropped due to a recipient previously marking your emails as spam. + spam_reports: + type: integer + description: The number of recipients who marked your email as spam. + unique_clicks: + type: integer + description: The number of unique recipients who clicked links in your emails. + unique_opens: + type: integer + description: The number of unique recipients who opened your emails. + unsubscribe_drops: + type: integer + description: The number of emails dropped due to a recipient unsubscribing from your emails. + unsubscribes: + type: integer + description: The number of recipients who unsubscribed from your emails. + required: + - date + - stats examples: application/json: - reputation: 100 - type: paid + - date: '2015-11-03' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-04' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-05' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-06' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-07' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-08' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + - date: '2015-11-09' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 0 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 security: - Authorization: [] - /whitelabel/ips: + /categories/stats/sums: parameters: [] get: tags: - - Whitelabel - IPs - summary: Retrieve all IP whitelabels + - Stats - Category Stats + summary: 'Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]' description: |- - **This endpoint allows you to retrieve all of the IP whitelabels that have been createdy by this account.** - - You may include a search key by using the "ip" parameter. This enables you to perform a prefix search for a given IP segment (e.g. "192."). + **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.** - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - operationId: GET_whitelabel-ips + 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). + operationId: GET_categories-stats-sums consumes: - application/json produces: - application/json parameters: + - name: sort_by_metric + in: query + description: The metric that you want to sort by. Must be a single metric. + required: false + type: string + default: delivered + - name: sort_by_direction + in: query + description: The direction you want to sort. + required: false + type: string + default: desc + enum: + - desc + - asc + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string - name: limit in: query - description: The number of results to retrieve. + description: Limits the number of results returned. + required: false type: integer + default: 5 - name: offset in: query - description: The point in the list of results to begin retrieving IPs from. - type: integer - - name: ip - in: query - description: The IP segment that you would like to use in a prefix search. - type: string - responses: - '200': - description: '' - schema: - type: array - items: - $ref: '#/definitions/ip_whitelabel' - examples: - application/json: - - id: 1 - ip: 192.168.1.1 - rdns: o1.email.example.com - users: - - username: john@example.com - user_id: 7 - - username: jane@example.com - user_id: 8 - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.1 - - id: 2 - ip: 192.168.1.2 - rdns: o2.email.example.com - users: - - username: john@example.com - user_id: 7 - - username: jane@example2.com - user_id: 9 - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o2.email.example.com - data: 192.168.1.2 - security: - - Authorization: [] - post: - tags: - - Whitelabel - IPs - summary: Create an IP whitelabel - description: |- - **This endpoint allows you to create an IP whitelabel.** - - When creating an IP whitelable, you should use the same subdomain that you used when you created a domain whitelabel. - - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - operationId: POST_whitelabel-ips - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - ip: - type: string - description: The IP address that you want to whitelabel. - subdomain: - type: string - description: The subdomain that will be used to send emails from the IP. Should be the same as the subdomain used for your domain whitelabel. - domain: - type: string - description: 'The root, or sending, domain that will be used to send message from the IP.' - required: - - ip - - subdomain - - domain - example: - ip: 192.168.1.1 - subdomain: email - domain: example.com + description: The point in the list to begin retrieving results. + required: false + type: integer + default: 0 + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: - '201': + '200': description: '' schema: - $ref: '#/definitions/ip_whitelabel' + type: object + properties: + '': + $ref: '#/definitions/category_stats' examples: application/json: - id: 123 - ip: 192.168.1.2 - rdns: o1.email.example.com - users: [] - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.2 + date: '2015-01-01' + stats: + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 20 + deferred: 0 + delivered: 20 + invalid_emails: 0 + opens: 20 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 20 + unique_opens: 20 + unsubscribe_drops: 0 + unsubscribes: 20 + name: cat1 + type: category + - metrics: + blocks: 1 + bounce_drops: 0 + bounces: 0 + clicks: 19 + deferred: 0 + delivered: 19 + invalid_emails: 0 + opens: 19 + processed: 0 + requests: 20 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 19 + unique_opens: 19 + unsubscribe_drops: 0 + unsubscribes: 19 + name: cat2 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 5 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 5 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 5 + name: cat3 + type: category + - metrics: + blocks: 0 + bounce_drops: 0 + bounces: 0 + clicks: 6 + deferred: 0 + delivered: 5 + invalid_emails: 0 + opens: 6 + processed: 0 + requests: 5 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 5 + unique_opens: 5 + unsubscribe_drops: 0 + unsubscribes: 6 + name: cat4 + type: category + - metrics: + blocks: 10 + bounce_drops: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + invalid_emails: 0 + opens: 0 + processed: 0 + requests: 10 + spam_report_drops: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + unsubscribe_drops: 0 + unsubscribes: 0 + name: cat5 + type: category security: - Authorization: [] - '/contactdb/segments/{segment_id}/recipients': - parameters: - - name: segment_id - in: path - description: The ID of the segment from which you want to retrieve recipients. - required: true - type: integer + /tracking_settings/open: + parameters: [] get: - summary: Retrieve recipients on a segment + summary: Get Open Tracking Settings description: |- - **This endpoint allows you to retrieve all of the recipients in a segment with the given ID.** + **This endpoint allows you to retrieve your current settings for open tracking.** - The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + 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. - For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). - operationId: GET_contactdb-segments-segment_id-recipients + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-open consumes: - application/json produces: - application/json - parameters: - - name: page - in: query - type: integer - - name: page_size - in: query - type: integer + parameters: [] responses: '200': description: '' schema: - title: List Recipients On a Segment response type: object properties: - recipients: - type: array - items: - $ref: '#/definitions/contactdb_recipient' + enabled: + type: boolean + description: Indicates if open tracking is enabled. required: - - recipients - examples: - application/json: - recipients: - - created_at: 1422313607 - email: jones@example.com - first_name: null - id: YUBh - last_clicked: null - last_emailed: null - last_name: Jones - last_opened: null - updated_at: 1422313790 - custom_fields: - - id: 23 - name: pet - value: Indiana - type: text - '400': - description: |- - "page" : "Returned if page is not a valid integer" - "page" : "Returned if page is less than 1" - "page_size" : "Returned if page_size is not a valid integer" - schema: - type: object - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + - enabled examples: application/json: - errors: - - field: null - message: authorization required - '404': - description: |- - "segment_id" : "Returned if segment_id is not valid" - "segment_id" : "Returned if segment_id does not exist" - schema: - type: object + enabled: true security: - Authorization: [] - /suppression/bounces: - parameters: [] - delete: - tags: - - Bounces API - summary: Delete bounces + patch: + summary: Update Open Tracking Settings description: |- - **This endpoint allows you to delete all of your bounces. You can also use this endpoint to remove a specific email address from your bounce list.** - - Bounces are messages that are returned to the server that sent it. + **This endpoint allows you to update your current settings for open tracking.** - For more information see: + 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. - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - * [Classroom > List Scrubbing Guide](https://sendgrid.com/docs/Classroom/Deliver/list_scrubbing.html) + 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. - Note: the `delete_all` and `emails` parameters should be used independently of each other as they have different purposes. - operationId: DELETE_suppression-bounces + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-open consumes: - application/json produces: @@ -5424,174 +4898,120 @@ paths: schema: type: object properties: - delete_all: + enabled: type: boolean - description: This parameter allows you to delete **every** email in your bounce list. This should not be used with the emails parameter. - emails: - type: array - description: Delete multiple emails from your bounce list at the same time. This should not be used with the delete_all parameter. - items: - type: string + description: The new status that you want to set for open tracking. example: - delete_all: true - emails: - - example@example.com - - example2@example.com + enabled: true responses: - '204': - description: '' - schema: - type: 'null' - '401': + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + enabled: + type: boolean + description: Indicates if open tracking is enabled. + required: + - enabled examples: application/json: - errors: - - field: null - message: authorization required + enabled: true security: - Authorization: [] + /tracking_settings/subscription: + parameters: [] get: - tags: - - Bounces API - summary: Retrieve all bounces + summary: Retrieve Subscription Tracking Settings description: |- - **This endpoint allows you to retrieve all of your bounces.** + **This endpoint allows you to retrieve your current settings for subscription tracking.** - Bounces are messages that are returned to the server that sent it. + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - For more information see: + 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. - * [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information - * [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) - operationId: GET_suppression-bounces + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-subscription consumes: - application/json produces: - application/json - parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when a bounce was created (inclusive). - type: number - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when a bounce was created (inclusive). - type: number - - name: Allow - in: header - description: '' - type: string + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: number - email: - type: string - reason: - type: string - status: - type: string - examples: - application/json: - - created: 1250337600 - email: example@example.com - reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ' - status: 5.1.1 - - created: 1250337600 - email: example@example.com - reason: '550 5.1.1Something something unsubscribe <% %> something something
+ landing: | +subscribehere
+ plain_content: Something something unsubscribe <% %> something something + replace: thetag + url: '' security: - Authorization: [] - /subusers: - parameters: [] - get: - tags: - - Subusers API - summary: List all Subusers + patch: + summary: Update Subscription Tracking Settings description: |- - This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + **This endpoint allows you to update your current settings for subscription tracking.** - For more information about Subusers: + Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - operationId: GET_subusers + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-subscription consumes: - application/json produces: - application/json parameters: - - name: username - in: query - description: The username of this subuser. - type: string - - name: limit - in: query - description: The number of results you would like to get in each request. - type: number - - name: offset - in: query - description: The number of subusers to skip. - type: number + - name: body + in: body + schema: + $ref: '#/definitions/subscription_tracking_settings' + example: + enabled: true + landing: landing page html + url: url + replace: replacement tag + html_content: html content + plain_content: text content responses: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/subuser' - examples: - application/json: - - disabled: false - email: example@example.com - id: 1234 - username: example_subuser - - disabled: false - email: example2@example.com - id: 1234 - username: example_subuser2 - '401': - description: Unexpected error in API call. See HTTP response body for details. - schema: - $ref: '#/definitions/global:ErrorResponse' + $ref: '#/definitions/subscription_tracking_settings' examples: application/json: - errors: - - field: null - message: authorization required + enabled: true + landing: landing page html + url: url + replace: replacement tag + html_content: html content + plain_content: text content security: - Authorization: [] + '/ips/pools/{pool_name}/ips': + parameters: + - name: pool_name + in: path + description: The name of the IP pool that you want to add an IP address to. + required: true + type: string post: - tags: - - Subusers API - summary: Create Subuser + summary: Add an IP address to a pool description: |- - This endpoint allows you to retrieve a list of all of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. + **This endpoint allows you to add an IP address to an IP pool.** - For more information about Subusers: + 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. - * [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) - * [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) - operationId: POST_subusers + 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. + operationId: POST_ips-pools-pool_name-ips consumes: - application/json produces: @@ -5602,95 +5022,82 @@ paths: schema: type: object properties: - username: - type: string - description: The username for this subuser. - email: + ip: type: string - description: The email address of the subuser. - format: email - password: + description: The IP address that you want to add to an IP pool. + example: + ip: 0.0.0.0 + responses: + '201': + description: '' + schema: + type: object + properties: + ip: type: string - description: The password this subuser will use when logging into SendGrid. - ips: + description: The IP address. + pools: type: array - description: The IP addresses that should be assigned to this subuser. + description: The list of IP pools that this IP address has been added to. items: type: string - format: ipv4 + 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: - - username - - email - - password - - ips - example: - username: John@example.com - email: John@example.com - password: johns_password - ips: - - 1.1.1.1 - - 2.2.2.2 - responses: - '200': - description: '' - schema: - $ref: '#/definitions/subuser_post' - examples: - application/json: - username: example_subuser - user_id: 1234 - email: example@example.com - signup_session_token: '' - authorization_token: '' - credit_allocation: - type: unlimited - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - message: username exists - - message: unable to validate IPs at this time - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + - ip + - pools + - start_date + - warmup examples: application/json: - errors: - - message: you dont have permission to access this resource - '500': + ip: 000.00.00.0 + pools: + - test1 + start_date: 1409616000 + warmup: true + '404': description: '' schema: type: object + properties: + errors: + type: array + description: The error returned. + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the IP address could not be added to the IP Pool. examples: application/json: errors: - - message: unable to validate IPs at this time + - field: null + message: resource not found security: - Authorization: [] - /contactdb/recipients/count: - parameters: [] + '/ips/{ip_address}': + parameters: + - name: ip_address + in: path + description: The IP address you are retrieving the IP pools for. + required: true + type: string get: - tags: - - Contacts API - Recipients - summary: Retrieve a Count of Recipients + summary: Retrieve all IP pools an IP address belongs to description: |- - **This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.** + **This endpoint allows you to see which IP pools a particular IP address has been added to.** - The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). - operationId: GET_contactdb-recipients-count + 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. + operationId: GET_ips-ip_address consumes: - application/json produces: @@ -5700,294 +5107,280 @@ paths: '200': description: '' schema: - $ref: '#/definitions/contactdb_recipient_count' - examples: - application/json: - recipient_count: 1234 - '401': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: object + properties: + ip: + type: string + description: The IP address. + subusers: + type: array + description: The subusers that can send email using this IP address. + items: + type: string + rdns: + type: string + description: The reverse DNS record for this IP address. + pools: + type: array + description: The list of IP pools that this IP address belongs to. + items: + type: string + warmup: + type: boolean + description: Indicates if this IP address is currently warming up. + start_date: + type: + - integer + - 'null' + description: The date that the IP address was entered into warmup. + whitelabeled: + type: boolean + description: Indicates if this IP address has been whitelabeled. + required: + - ip + - subusers + - rdns + - pools + - warmup + - start_date + - whitelabeled examples: application/json: - errors: - - field: null - message: authorization required + ip: 000.00.00.0 + subusers: + - subuser1 + - subuser2 + rdns: o1.em.example.com + pools: + - test1 + warmup: false + start_date: null + whitelabeled: true security: - Authorization: [] - '/campaigns/{campaign_id}': - parameters: - - name: campaign_id - in: path - description: The ID of the campaign that you would like to delete. - required: true - type: integer - delete: - summary: Delete a Campaign + /user/webhooks/event/settings: + parameters: [] + get: + tags: + - Webhooks + summary: Retrieve Event Webhook settings description: |- - **This endpoint allows you to delete a specific campaign.** + **This endpoint allows you to retrieve your current event webhook settings.** - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + If an event type is marked as `true`, then the event webhook will include information about that event. - For more information: + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: DELETE_campaigns-campaign_id + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + operationId: GET_user-webhooks-event-settings consumes: - application/json produces: - application/json - parameters: - - name: body - in: body - schema: - type: 'null' + parameters: [] responses: - '204': - description: '' - schema: - type: 'null' - '401': + '200': description: '' schema: - type: object + $ref: '#/definitions/event_webhook_settings' examples: application/json: - errors: - - field: null - message: authorization required - '404': - description: '"": "not found"' - schema: - type: object + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true security: - Authorization: [] - get: - summary: Retrieve a single campaign + patch: + tags: + - Webhooks + summary: Update Event Notification Settings description: |- - **This endpoint allows you to retrieve a specific campaign.** + **This endpoint allows you to update your current event webhook settings.** - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + If an event type is marked as `true`, then the event webhook will include information about that event. - For more information: + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: GET_campaigns-campaign_id + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + operationId: PATCH_user-webhooks-event-settings consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + $ref: '#/definitions/event_webhook_settings' + example: + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true responses: '200': description: '' schema: - $ref: '#/definitions/campaign_response' - examples: - application/json: - id: 986724 - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:Check out our spring line!
- plain_content: Check out our spring line! - status: Draft - '401': - description: '' - schema: - type: object - examples: - application/json: - errors: - - field: null - message: authorization required - '404': - description: '"": "not found"' - schema: - type: object + $ref: '#/definitions/event_webhook_settings' examples: application/json: - errors: - - field: null - message: not found + enabled: true + url: url + group_resubscribe: true + delivered: true + group_unsubscribe: true + spam_report: true + bounce: true + deferred: true + unsubscribe: true + processed: true + open: true + click: true + dropped: true security: - Authorization: [] - patch: - summary: Update a Campaign + '/suppression/blocks/{email}': + parameters: + - name: email + in: path + description: The blocked email address that you want to delete. + required: true + type: string + delete: + tags: + - Blocks API + summary: Delete a specific block 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: + **This endpoint allows you to delete a specific email address from your blocks list.** - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: PATCH_campaigns-campaign_id + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: DELETE_suppression-blocks-email consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: - title: Update a Campaign request - type: object - properties: - title: - type: string - description: The title of the campaign. - subject: - type: string - description: The subject line for your campaign. - categories: - type: array - description: The categories you want to tag on this campaign. - items: - type: string - html_content: - type: string - description: The HTML content of this campaign. - plain_content: - type: string - description: The plain content of this campaign. - required: - - title - - subject - - categories - - html_content - - plain_content - example: - title: May Newsletter - subject: New Products for Summer! - categories: - - summer line - html_content:Check out our summer line!
- plain_content: Check out our summer line! + type: 'null' responses: - '200': + '204': description: '' - schema: - $ref: '#/definitions/campaign_response' - examples: - application/json: - id: 986724 - title: May Newsletter - subject: New Products for Summer! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - summer line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:Check out our summer line!
- plain_content: Check out our summer line! - status: Draft - '400': - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." schema: type: object - examples: - application/json: - errors: - - field: title - message: title can't be blank - - field: title - message: title is too long (maximum is 100 characters) - - field: categories - message: categories exceeds 10 category limit - - field: html_content - message: html_content exceeds the 1MB limit - - field: plain_content - message: plain_content exceeds the 1MB limit - - field: sender_id - message: sender_id does not exist - - field: sender_id - message: sender_id is not a verified sender identity - - field: list_ids - message: list_ids do not all exist - - field: segment_ids - message: segment_ids do not all exist - - field: ip_pool - message: The ip pool you provided is invalid - - field: suppression_group_id - message: suppression_group_id does not exist - - field: unsubscribes - message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - - field: null - message: The JSON you have submitted cannot be parsed. - '401': + properties: {} + get: + tags: + - Blocks API + summary: Retrieve a specific block + description: |- + **This endpoint allows you to retrieve a specific email address from your blocks list.** + + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: GET_suppression-blocks-email + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - '403': - description: '"": "You may only update a campaign when it is in draft mode."' - schema: - type: object - examples: - application/json: - errors: - - field: null - message: You may only update a campaign when it is in draft mode. - '404': - description: '"": "not found"' - schema: - $ref: '#/definitions/global:ErrorResponse' + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the block was created. + email: + type: string + description: The email address of the recipient that was blocked. + reason: + type: string + description: The reason why the email was blocked. + status: + type: string + description: The status of the block. + required: + - created + - email + - reason examples: application/json: - errors: - - field: null - message: not found + - created: 1443651154 + email: user1@example.com + reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' + status: 4.0.0 security: - Authorization: [] - '/mail/batch/{batch_id}': + '/suppression/invalid_emails/{email}': parameters: - - name: batch_id + - name: email in: path + description: The invalid email address that you want to remove. required: true type: string + delete: + summary: Delete a specific invalid email + description: |- + **This endpoint allows you to remove a specific email address from the invalid email address list.** + + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: DELETE_suppression-invalid_emails-email + consumes: + - application/json + produces: [] + parameters: + - name: body + in: body + schema: + type: 'null' + responses: + '204': + description: '' + schema: + type: object + properties: {} get: - summary: Validate batch ID + summary: Retrieve a specific invalid email description: |- - **This endpoint allows you to validate a batch ID.** + **This endpoint allows you to retrieve a specific invalid email addresses.** - 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. + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - More Information: + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) - operationId: GET_mail-batch-batch_id + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: GET_suppression-invalid_emails-email consumes: - application/json produces: @@ -5997,104 +5390,69 @@ paths: '200': description: '' schema: - $ref: '#/definitions/mail_batch_id' - examples: - application/json: - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi - '400': - description: '' - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: invalid batch id - '401': - description: Unexpected error in API call. See HTTP response body for details. - schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required - security: - - Authorization: [] - /user/profile: - parameters: [] - patch: - tags: - - Users API - summary: Update a user's profile + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the email address was added to the invalid emails list. + email: + type: string + description: The email address that was marked as invalid. + reason: + type: string + description: A reason explaining why the email address was marked as invalid. + required: + - created + - email + - reason + examples: + application/json: + - created: 1454433146 + email: test1@example.com + reason: Mail domain mentioned in email address is unknown + '/suppression/spam_report/{email}': + parameters: + - name: email + in: path + description: The email address for the spam report that you want to delete. + required: true + type: string + delete: + summary: Delete a specific spam report description: |- - **This endpoint allows you to update your current profile details.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: + **This endpoint allows you to delete a specific spam report.** - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. - It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. - operationId: PATCH_user-profile + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: DELETE_suppression-spam_report-email consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: - $ref: '#/definitions/user_profile' - example: - first_name: Example - last_name: User - city: Orange - - name: on-behalf-of - in: header - description: 'You can enter a subuser name as the value for this header, in order to update the subuser''s profile.' - type: string + type: 'null' responses: - '200': - description: '' - schema: - $ref: '#/definitions/user_profile' - examples: - application/json: - address: 814 West Chapman Avenue - address2: '' - city: Orange - company: SendGrid - country: US - first_name: Example - last_name: User - phone: 555-555-5555 - state: CA - website: 'http://www.sendgrid.com' - zip: '92868' - '401': + '204': description: '' schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: authorization required + type: object + properties: {} security: - Authorization: [] get: - tags: - - Users API - summary: Get a user's profile + summary: Retrieve a specific spam report description: |- - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + **This endpoint allows you to retrieve a specific spam report.** - For more information about your user profile: + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: GET_user-profile + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: GET_suppression-spam_report-email consumes: - application/json produces: @@ -6104,269 +5462,286 @@ paths: '200': description: '' schema: - title: GET User Profile response - type: object - properties: - address: - type: string - description: The user's address. - address2: - type: string - description: The second line of the user's address. - city: - type: string - description: The user's city. - company: - type: string - description: The name of the user's company. - country: - type: string - description: The user's country. - first_name: - type: string - description: The user's first name. - last_name: - type: string - description: The user's last name. - phone: - type: string - description: The user's phone number. - state: - type: string - description: The user's state. - website: - type: string - description: The user's website URL. - zip: - type: string - description: The user's zip code. - required: - - address - - city - - company - - country - - first_name - - last_name - - phone - - state - - website - - zip + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp that indicates when the recipient marked your message as spam. + email: + type: string + description: The email address of the recipient that marked your message as spam. + ip: + type: string + description: The IP address that the message was sent from. + required: + - created + - email + - ip examples: application/json: - address: 814 West Chapman Avenue - address2: '' - city: Orange - company: SendGrid - country: US - first_name: Test - last_name: User - phone: 555-555-5555 - state: CA - website: 'http://www.sendgrid.com' - zip: '92868' - '401': - description: '' - schema: - type: object + - created: 1454433146 + email: test1@example.com + ip: 10.89.32.5 security: - Authorization: [] - '/campaigns/{campaign_id}/schedules/test': + '/access_settings/whitelist/{rule_id}': parameters: - - name: campaign_id + - name: rule_id in: path + description: The ID of the whitelisted IP address that you want to retrieve. required: true - type: integer - post: - summary: Send a Test Campaign + type: string + get: + summary: Retrieve a specific whitelisted IP description: |- - **This endpoint allows you to send a test campaign.** + **This endpoint allows you to retreive a specific IP address that has been whitelisted.** - To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] + You must include the ID for the specific IP address you want to retrieve in your call. - For more information: + 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. - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: POST_campaigns-campaign_id-schedules-test + For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). + operationId: GET_access_settings-whitelist-rule_id consumes: - application/json produces: - application/json - parameters: - - name: body - in: body - schema: - type: object - properties: - to: - type: string - description: The email address that should receive the test campaign. - format: email - required: - - to - example: - to: your.email@example.com + parameters: [] responses: - '204': + '200': description: '' schema: - title: Send a Test Campaign request type: object properties: - to: + 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: - - to - '400': - description: |- - "": "The JSON you have submitted cannot be parsed." - "to": "Please provide an email address to which the test should be sent." - "to": "You can only send tests to 10 addresses at a time." - "subject": "Please add a subject to your campaign before sending a test." - "plain_content": "Plain content and html content can't both be blank. Please set one of these values before sending a test." - "sender_id": "Please assign a sender identity to your campaign before sending a test." - schema: - $ref: '#/definitions/global:ErrorResponse' + - id + - ip + - created_at + - updated_at examples: application/json: - errors: - - field: send_at - message: Please choose a future time for sending your campaign. - - field: null - message: The JSON you have submitted cannot be parsed. - - field: null - message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' - '404': - description: '"": "not found"' + id: 1 + ip: 192.168.1.1 + created_at: 1441824715 + updated_at: 1441824715 + security: + - Authorization: [] + delete: + summary: 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). + operationId: DELETE_access_settings-whitelist-rule_id + consumes: + - application/json + produces: [] + parameters: + - name: body + in: body schema: - $ref: '#/definitions/global:ErrorResponse' - examples: - application/json: - errors: - - field: null - message: not found + type: 'null' + responses: + '204': + description: '' + schema: + type: object + properties: {} security: - Authorization: [] - /ips/assigned: + /access_settings/activity: parameters: [] get: - tags: - - IP Addresses - summary: Retrieve all assigned IPs + summary: Retrieve all recent access attempts description: |- - **This endpoint allows you to retrieve only assigned IP addresses.** + **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.** - 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. - operationId: GET_ips-assigned + 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). + operationId: GET_access_settings-activity consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: limit + in: query + description: Limits the number of IPs to return. + type: integer + default: 20 responses: '200': description: '' schema: - type: array - title: List all assigned IPs response - items: - type: object - properties: - ip: - type: string - description: The IP address. - pools: - type: array - description: The IP pools that this IP address has been added to. - items: - type: string - warmup: - type: boolean - description: Indicates if this IP address is currently warming up. - start_date: - type: integer - description: The start date that this IP address was entered into warmup. - required: - - ip - - pools - - warmup - - start_date + type: object + properties: + result: + type: array + description: An array containing the IPs that recently attempted to access your account. + items: + type: object + properties: + allowed: + type: boolean + description: Indicates if the IP address was granted access to the account. + auth_method: + type: string + description: The authentication method used when attempting access. + first_at: + type: integer + description: A Unix timestamp indicating when the first access attempt was made. + ip: + type: string + description: The IP addressed used during the access attempt. + last_at: + type: integer + description: A Unix timestamp indicating when the most recent access attempt was made + location: + type: string + description: The geographic location from which the access attempt originated. + required: + - allowed + - auth_method + - first_at + - ip + - last_at + - location + required: + - result examples: application/json: - - ip: 167.89.21.3 - pools: - - new_test5 - warmup: true - start_date: 1409616000 + 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' security: - Authorization: [] - /whitelabel/links/default: + /access_settings/whitelist: parameters: [] - get: - tags: - - Whitelabel - Links - summary: Retrieve a Default Link Whitelabel + post: + summary: Add one or more IPs to the whitelist description: |- - **This endpoint allows you to retrieve the default link whitelabel.** + **This endpoint allows you to add one or more IP addresses to your IP whitelist.** - Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: -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 + - date: '2015-10-11' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-12' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-13' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-14' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-15' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-16' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-17' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-18' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-19' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-20' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-21' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 1 + drops: 0 + opens: 1 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 1 + - date: '2015-10-22' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-23' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-24' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-25' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-26' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 2 + drops: 0 + opens: 2 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 2 + - date: '2015-10-27' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-28' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-29' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-30' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-10-31' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-01' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-02' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-03' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-04' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-05' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-06' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-07' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-08' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-09' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 + - date: '2015-11-10' + stats: + - type: mailbox_provider + name: Gmail + metrics: + blocks: 0 + bounces: 0 + clicks: 0 + deferred: 0 + delivered: 0 + drops: 0 + opens: 0 + spam_reports: 0 + unique_clicks: 0 + unique_opens: 0 security: - - Authorization: [] - post: - tags: - - Campaigns API - summary: Create a Campaign + - Authorization: [] + '/api_keys/{api_key_id}': + parameters: + - name: api_key_id + in: path + required: true + type: string + delete: + summary: Delete API keys description: |- - **This endpoint allows you to create a campaign.** + **This endpoint allows you to revoke an existing API Key** - Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + Authentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned. - 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. + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - For more information: + ## URI Parameters - * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) - operationId: POST_campaigns + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are deleting.| + operationId: DELETE_api_keys-api_key_id consumes: - application/json produces: @@ -7276,223 +6997,156 @@ paths: - name: body in: body schema: - $ref: '#/definitions/campaign_request' - example: - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:Check out our spring line!
- plain_content: Check out our spring line! + type: 'null' responses: - '201': + '204': description: '' schema: - $ref: '#/definitions/campaign_response' + type: 'null' examples: - application/json: - id: 986724 - title: March Newsletter - subject: New Products for Spring! - sender_id: 124451 - list_ids: - - 110 - - 124 - segment_ids: - - 110 - categories: - - spring line - suppression_group_id: 42 - custom_unsubscribe_url: '' - ip_pool: marketing - html_content:Check out our spring line!
- plain_content: Check out our spring line! - status: Draft - '400': - description: |- - "title": "title can't be blank" - "title": "title is too long (maximum is 100 characters)" - "categories": "categories exceeds 10 category limit" - "html_content": "html_content exceeds the 1MB limit" - "plain_content": "plain_content exceeds the 1MB limit" - "sender_id": "sender_id does not exist" - "sender_id": "sender_id is not a verified sender identity" - "list_ids": "list_ids do not all exist" - "segment_ids": "segment_ids do not all exist" - "ip_pool": "The ip pool you provided is invalid" - "suppression_group_id": "suppression_group_id does not exist" - "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." - "": "The JSON you have submitted cannot be parsed." - "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." + application/json: null + '404': + description: '' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: title - message: title can't be blank - - field: title - message: title is too long (maximum is 100 characters) - - field: categories - message: categories exceeds 10 category limit - - field: html_content - message: html_content exceeds the 1MB limit - - field: plain_content - message: plain_content exceeds the 1MB limit - - field: sender_id - message: sender_id does not exist - - field: sender_id - message: sender_id is not a verified sender identity - - field: list_ids - message: list_ids do not all exist - - field: segment_ids - message: segment_ids do not all exist - - field: ip_pool - message: The ip pool you provided is invalid - - field: suppression_group_id - message: suppression_group_id does not exist - - field: unsubscribes - message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - - field: null - message: The JSON you have submitted cannot be parsed. - field: null - message: You've reached your limit of 250 campaigns. Please delete one or more and try again. - '401': - description: '' - schema: - type: object + message: unable to find API Key security: - Authorization: [] - '/whitelabel/ips/{id}': - parameters: - - name: id - in: path - description: The id of the IP whitelabel that you would like to retrieve. - required: true - type: string - get: - tags: - - Whitelabel - IPs - summary: Retrieve an IP whitelabel - description: |- - **This endpoint allows you to retrieve an IP whitelabel.** + put: + summary: Update the name & scopes of an API Key + description: | + **This endpoint allows you to update the name and scopes of a given API key.** - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + A JSON request body with a "name" property is required. + Most provide the list of all the scopes an api key should have. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - operationId: GET_whitelabel-ips-id + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + operationId: PUT_api_keys-api_key_id consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + scopes: + type: array + items: + type: string + example: + name: A New Hope + scopes: + - user.profile.read + - user.profile.update responses: '200': description: '' schema: - $ref: '#/definitions/ip_whitelabel' + $ref: '#/definitions/api_key_name_id_scopes' examples: application/json: - id: 123 - ip: 192.168.1.1 - rdns: o1.email.example.com - users: - - username: john@example.com - user_id: 7 - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.1 - '404': + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + scopes: + - user.profile.read + - user.profile.update + '400': + description: Unexpected error in API call. See HTTP response body for details. + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: expected JSON request body with 'name' property + '401': description: '' schema: type: object - properties: - errors: - type: array - description: The errors preventing the retrieval of the IP whitelabel. - items: - type: object - properties: - message: - type: string - description: A message explaining why the IP whitelabel could not be found. - required: - - message - required: - - errors + '404': + description: Unexpected error in API call. See HTTP response body for details. + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: Whitelabel ip not found. + - field: null + message: unable to find API Key to update security: - Authorization: [] - delete: - tags: - - Whitelabel - IPs - summary: Delete an IP whitelabel + get: + summary: Retrieve an existing API Key description: |- - **This endpoint allows you to delete an IP whitelabel.** - - A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + **This endpoint allows you to retrieve a single api key.** - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). - operationId: DELETE_whitelabel-ips-id + If the API Key ID does not exist an HTTP 404 will be returned. + operationId: GET_api_keys-api_key_id consumes: - application/json produces: - application/json parameters: [] responses: - '204': - description: '' - schema: - type: object - '404': + '200': description: '' schema: type: object properties: - errors: + result: type: array - description: The errors preventing the IP whitelabel from being deleted. items: - type: object - properties: - message: - type: string - description: A message explaining why the IP whitelabel could not be deleted. + $ref: '#/definitions/api_key_name_id_scopes' + examples: + application/json: + result: + - name: API Key Name + api_key_id: some-apikey-id + - name: API Key Name 2 + api_key_id: another-apikey-id + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: Unexpected error in API call. See HTTP response body for details. + schema: + type: object examples: application/json: errors: - - message: Whitelabel ip not found. + - field: null + message: unable to find API Key security: - Authorization: [] - /mail_settings/bounce_purge: - parameters: [] patch: - summary: Update bounce purge mail settings + summary: Update API keys description: |- - **This endpoint allows you to update your current bounce purge settings.** + **This endpoint allows you to update the name of an existing API Key.** - This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + A JSON request body with a "name" property is required. - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: PATCH_mail_settings-bounce_purge + The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + + ## URI Parameters + + | URI Parameter | Type | Required? | Description | + |---|---|---|---| + |api_key_id |string | required | The ID of the API Key you are updating.| + operationId: PATCH_api_keys-api_key_id consumes: - application/json produces: @@ -7501,32 +7155,46 @@ paths: - name: body in: body schema: - $ref: '#/definitions/mail_settings_bounce_purge' + type: object + properties: + name: + type: string + description: The new name of the API Key. example: - enabled: true - hard_bounces: 5 - soft_bounces: 5 + name: A New Hope responses: '200': description: '' schema: - $ref: '#/definitions/mail_settings_bounce_purge' + $ref: '#/definitions/api_key_name_id' examples: application/json: - enabled: false - hard_bounces: null - soft_bounces: null + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required security: - Authorization: [] + /user/profile: + parameters: [] get: - summary: Retrieve bounce purge mail settings + tags: + - Users API + summary: Get a user's profile description: |- - **This endpoint allows you to retrieve your current bounce purge settings.** + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + For more information about your user profile: - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings-bounce_purge + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + operationId: GET_user-profile consumes: - application/json produces: @@ -7536,235 +7204,374 @@ paths: '200': description: '' schema: - $ref: '#/definitions/mail_settings_bounce_purge' + title: GET User Profile response + type: object + properties: + address: + type: string + description: The user's address. + address2: + type: string + description: The second line of the user's address. + city: + type: string + description: The user's city. + company: + type: string + description: The name of the user's company. + country: + type: string + description: The user's country. + first_name: + type: string + description: The user's first name. + last_name: + type: string + description: The user's last name. + phone: + type: string + description: The user's phone number. + state: + type: string + description: The user's state. + website: + type: string + description: The user's website URL. + zip: + type: string + description: The user's zip code. + required: + - address + - city + - company + - country + - first_name + - last_name + - phone + - state + - website + - zip examples: application/json: - enabled: false - soft_bounces: 1234 - hard_bounces: null + address: 814 West Chapman Avenue + address2: '' + city: Orange + company: SendGrid + country: US + first_name: Test + last_name: User + phone: 555-555-5555 + state: CA + website: 'http://www.sendgrid.com' + zip: '92868' + '401': + description: '' + schema: + type: object security: - Authorization: [] - /whitelabel/links: - parameters: [] - post: + patch: tags: - - Whitelabel - Links - summary: Create a Link Whitelabel + - Users API + summary: Update a user's profile description: |- - **This endpoint allows you to create a new link whitelabel.** + **This endpoint allows you to update your current profile details.** - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: POST_whitelabel-links + For more information about your user profile: + + * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + + It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. + operationId: PATCH_user-profile consumes: - application/json produces: - application/json parameters: - - name: limit - in: query - description: Number of domains to return. - type: integer - default: 50 - - name: offset - in: query - description: Paging offset. - type: integer - default: 0 - name: body in: body schema: - type: object - properties: - domain: - type: string - description: The root domain for your subdomain that you are creating the whitelabel for. This should match your FROM email address. - subdomain: - type: string - description: The subdomain to create the link whitelabel for. Must be different from the subdomain you used for a domain whitelabel. - default: - type: boolean - description: 'Indicates if you want to use this link whitelabel as the fallback, or default, whitelabel.' - enum: - - true - - false - required: - - domain - - subdomain + $ref: '#/definitions/user_profile' example: - domain: example.com - subdomain: mail - default: true + first_name: Example + last_name: User + city: Orange + - name: on-behalf-of + in: header + description: 'You can enter a subuser name as the value for this header, in order to update the subuser''s profile.' + type: string responses: - '201': + '200': description: '' schema: - $ref: '#/definitions/link_whitelabel' + $ref: '#/definitions/user_profile' examples: application/json: - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: false - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net + address: 814 West Chapman Avenue + address2: '' + city: Orange + company: SendGrid + country: US + first_name: Example + last_name: User + phone: 555-555-5555 + state: CA + website: 'http://www.sendgrid.com' + zip: '92868' + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + '/user/scheduled_sends/{batch_id}': + parameters: + - name: batch_id + in: path + required: true + type: string + get: + summary: Retrieve scheduled send + description: |- + **This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.** + + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: GET_user-scheduled_sends-batch_id + consumes: + - application/json + produces: + - application/json + parameters: [] + responses: + '200': + description: '' + schema: + type: array + title: Retrieve scheduled send response + items: + $ref: '#/definitions/user_scheduled_send_status' + examples: + application/json: + - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + status: cancel + - batch_id: IbLdyLYULb7Rj8GKSx7u025ouWVlAiMg + status: pause + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required security: - Authorization: [] - get: - tags: - - Whitelabel - Links - summary: Retrieve all link whitelabels + patch: + summary: Update user scheduled send information description: |- - **This endpoint allows you to retrieve all link whitelabels.** - - Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + **This endpoint allows you to update the status of a scheduled send for the given `batch_id`.** - For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). - operationId: GET_whitelabel-links + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: PATCH_user-scheduled_sends-batch_id consumes: - application/json produces: - application/json parameters: - - name: limit - in: query - description: Limits the number of results returned per page. - type: integer + - name: body + in: body + schema: + type: object + properties: + status: + type: string + description: The status you would like the scheduled send to have. + enum: + - cancel + - pause + required: + - status + example: + status: pause responses: - '200': + '204': description: '' schema: - type: array - items: - $ref: '#/definitions/link_whitelabel' + type: 'null' + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - - id: 1 - domain: example.com - subdomain: mail - username: john@example.com - user_id: 7 - default: true - valid: true - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: mail.example.com - data: sendgrid.net - owner_cname: - valid: true - type: cname - host: 7.example.com - data: sendgrid.net - - id: 2 - domain: example2.com - subdomain: news - username: john@example.com - user_id: 8 - default: false - valid: false - legacy: false - dns: - domain_cname: - valid: true - type: cname - host: news.example2.com - data: sendgrid.net - owner_cname: - valid: false - type: cname - host: 8.example2.com - data: sendgrid.net + errors: + - field: status + message: status must be either cancel or pause + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"" : "batch id not found"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: batch id not found security: - Authorization: [] - '/asm/suppressions/global/{email}': - parameters: - - name: email - in: path - description: The email address you want to remove from the global suppressions group. - required: true - type: string delete: - tags: - - Suppression Management - Global Suppressions - summary: Delete a Global Suppression + summary: Delete a cancellation or pause of a scheduled send description: |- - **This endpoint allows you to remove an email address from the global suppressions group.** + **This endpoint allows you to delete the cancellation/pause of a scheduled send.** - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: DELETE_asm-suppressions-global-email + The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + operationId: DELETE_user-scheduled_sends-batch_id consumes: - application/json - produces: [] - parameters: [] + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: 'null' responses: '204': description: '' schema: - type: object + type: 'null' + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: batch id not found security: - Authorization: [] + /campaigns: + parameters: [] get: tags: - - Suppression Management - Global Suppressions - summary: Retrieve a Global Suppression + - Campaigns API + summary: Retrieve all Campaigns description: |- - **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppresed.** + **This endpoint allows you to retrieve a list of all of your campaigns.** - If the email address you include in the URL path parameter `{email}` is alreayd globally suppressed, the response will include that email address. If the address you enter for `{email}` is not globally suppressed, an empty JSON object `{}` will be returned. + Returns campaigns in reverse order they were created (newest first). - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: GET_asm-suppressions-global-email + Returns an empty array if no campaigns exist. + + For more information: + + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: GET_campaigns consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: limit + in: query + description: The number of results you would like to receive at a time. + type: number + default: 10 + - name: offset + in: query + description: 'The index of the first campaign to return, where 0 is the first campaign.' + type: number + default: 0 responses: '200': description: '' schema: - title: Retrieve a Global Suppression response type: object properties: - recipient_email: - type: string - description: The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed. - required: - - recipient_email + result: + type: array + items: + $ref: '#/definitions/campaign_response' + examples: + application/json: + result: + - id: 986724 + title: March Newsletter + subject: New Products for Spring! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:Check out our spring line!
+ plain_content: Check out our spring line! + status: Draft + - id: 986723 + title: February Newsletter + subject: Final Winter Product Sale! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - winter line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:Last call for winter clothes!
+ plain_content: Last call for winter clothes! + status: Sent security: - Authorization: [] - /mail/batch: - parameters: [] post: tags: - - Cancel Scheduled Sends - summary: Create a batch ID + - Campaigns API + summary: Create a Campaign description: |- - **This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.** + **This endpoint allows you to create a campaign.** - 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. + Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - More Information: + 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: - * [Scheduling Parameters > Batch ID](https://sendgrid.com/docs/API_Reference/SMTP_API/scheduling_parameters.html) - operationId: POST_mail-batch + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: POST_campaigns consumes: - application/json produces: @@ -7773,71 +7580,151 @@ paths: - name: body in: body schema: - type: 'null' + $ref: '#/definitions/campaign_request' + example: + title: March Newsletter + subject: New Products for Spring! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:Check out our spring line!
+ plain_content: Check out our spring line! responses: '201': description: '' schema: - $ref: '#/definitions/mail_batch_id' + $ref: '#/definitions/campaign_response' examples: application/json: - batch_id: YOUR_BATCH_ID - '401': - description: '' + id: 986724 + title: March Newsletter + subject: New Products for Spring! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - spring line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:Check out our spring line!
+ plain_content: Check out our spring line! + status: Draft + '400': + description: |- + "title": "title can't be blank" + "title": "title is too long (maximum is 100 characters)" + "categories": "categories exceeds 10 category limit" + "html_content": "html_content exceeds the 1MB limit" + "plain_content": "plain_content exceeds the 1MB limit" + "sender_id": "sender_id does not exist" + "sender_id": "sender_id is not a verified sender identity" + "list_ids": "list_ids do not all exist" + "segment_ids": "segment_ids do not all exist" + "ip_pool": "The ip pool you provided is invalid" + "suppression_group_id": "suppression_group_id does not exist" + "unsubscribes": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." + "": "The JSON you have submitted cannot be parsed." + "": "You've reached your limit of 250 campaigns. Please delete one or more and try again." schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: + - field: title + message: title can't be blank + - field: title + message: title is too long (maximum is 100 characters) + - field: categories + message: categories exceeds 10 category limit + - field: html_content + message: html_content exceeds the 1MB limit + - field: plain_content + message: plain_content exceeds the 1MB limit + - field: sender_id + message: sender_id does not exist + - field: sender_id + message: sender_id is not a verified sender identity + - field: list_ids + message: list_ids do not all exist + - field: segment_ids + message: segment_ids do not all exist + - field: ip_pool + message: The ip pool you provided is invalid + - field: suppression_group_id + message: suppression_group_id does not exist + - field: unsubscribes + message: 'Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.' - field: null - message: authorization required + message: The JSON you have submitted cannot be parsed. + - field: null + message: You've reached your limit of 250 campaigns. Please delete one or more and try again. + '401': + description: '' + schema: + type: object security: - Authorization: [] - '/subusers/{subuser_name}/ips': - parameters: - - name: subuser_name - in: path - required: true - type: string - put: - summary: Update IPs assigned to a subuser + /contactdb/reserved_fields: + parameters: [] + get: + summary: Retrieve reserved fields description: |- - Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. - - More information: + **This endpoint allows you to list all fields that are reserved and can't be used for custom field names.** - * [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html) - * [IPs can be whitelabeled](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/ips.html) - operationId: PUT_subusers-subuser_name-ips + The contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html). + operationId: GET_contactdb-reserved_fields consumes: - application/json produces: - application/json - parameters: - - name: body - in: body - schema: - type: array - items: - type: string - format: ipv4 - example: - - 127.0.0.1 + parameters: [] responses: '200': description: '' schema: + title: List fields that are reserved and can't be used for custom field names. response type: object properties: - ips: + reserved_fields: type: array + description: The reserved fields that are already set up within custom fields. items: - type: string - format: ipv4 + $ref: '#/definitions/contactdb_custom_field' + required: + - reserved_fields examples: application/json: - ips: - - 127.0.0.1 + reserved_fields: + - name: first_name + type: text + - name: last_name + type: text + - name: email + type: text + - name: created_at + type: date + - name: updated_at + type: date + - name: last_emailed + type: date + - name: last_clicked + type: date + - name: last_opened + type: date + - name: my_custom_field + type: text '401': description: '' schema: @@ -7847,61 +7734,127 @@ paths: errors: - field: null message: authorization required - /api_keys: - parameters: [] + security: + - Authorization: [] + '/contactdb/lists/{list_id}/recipients': + parameters: + - name: list_id + in: path + description: The id of the list of recipients you want to retrieve. + required: true + type: integer get: - summary: Retrieve all API Keys belonging to the authenticated user + summary: Retrieve all recipients on a List description: |- - **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** + **This endpoint allows you to retrieve all recipients on the list with the given ID.** - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). - operationId: GET_api_keys + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: GET_contactdb-lists-list_id-recipients consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: page + in: query + description: Page index of first recipient to return (must be a positive integer) + required: false + type: integer + - name: page_size + in: query + description: Number of recipients to return at a time (must be a positive integer between 1 and 1000) + required: false + type: integer + - name: list_id + in: query + description: The ID of the list whose recipients you are requesting. + required: true + type: number responses: '200': description: '' schema: type: object properties: - result: + recipients: type: array items: - $ref: '#/definitions/api_key_name_id' + $ref: '#/definitions/contactdb_recipient' examples: application/json: - result: - - name: API Key Name - api_key_id: some-apikey-id - - name: API Key Name 2 - api_key_id: another-apikey-id - '401': - description: '' + recipients: + - created_at: 1433348344 + custom_fields: + - id: 6234 + name: age + type: number + value: null + - id: 6233 + name: country + type: text + value: null + - id: 6235 + name: fname + type: text + value: Example + - id: 6239 + name: lname + type: text + value: User + - id: 6240 + name: lname + type: text + value: null + email: example@example.com + first_name: Example + id: ZGVWfyZWsuYmFpbmVzQHNlbmRmCmLkLmNv== + last_clicked: 1438616117 + last_emailed: 1438613272 + last_name: User + last_opened: 1438616109 + updated_at: 1438616119 + '400': + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "page" : "Returned if page is not a valid integer" + "page" : "Returned if page is less than 1" + "page_size" : "Returned if page_size is not a valid integer" + "page_size" : "Returned if page_size is less than 1 or greater than 1000" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: authorization required + - field: list_id + message: Returned if list_id is not a valid integer + - field: page + message: Returned if page is not a valid integer + - field: page + message: Returned if page is less than 1 + - field: page_size + message: Returned if page_size is not a valid integer + - field: page_size + message: Returned if page_size is less than 1 or greater than 1000 + '404': + description: '"list_id" : "Returned if list_id does not exist"' + schema: + type: object + examples: + application/json: + errors: + - field: list_id + message: Returned if list_id is invalid security: - Authorization: [] post: - summary: Create API keys + summary: Add Multiple Recipients to a List description: |- - **This enpoint allows you to create a new random API Key for the user.** - - A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. - - There is a limit of 100 API Keys on your account. + **This endpoint allows you to add multiple recipients to a list.** - The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). + Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. - See the [API Key Permissions List](https://sendgrid.com/docs/API_Reference/Web_API_v3/API_Keys/api_key_permissions_list.html) for a list of all available scopes. - operationId: create-api-keys + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + operationId: POST_contactdb-lists-list_id-recipients consumes: - application/json produces: @@ -7910,58 +7863,36 @@ paths: - name: body in: body schema: - type: object - properties: - name: - type: string - description: The name you will use to describe this API Key. - scopes: - type: array - description: The individual permissions that you are giving to this API Key. - items: - type: string - required: - - name + type: array + items: + type: string example: - name: My API Key - scopes: - - mail.send - - alerts.create - - alerts.read + - recipient_id1 + - recipient_id2 responses: '201': description: '' schema: - type: object - properties: - api_key: - type: string - api_key_id: - type: string - name: - type: string - scopes: - type: array - items: - type: string - examples: - application/json: - api_key: SG.xxxxxxxx.yyyyyyyy - api_key_id: xxxxxxxx - name: My API Key - scopes: - - mail.send - - alerts.create - - alerts.read + type: 'null' '400': - description: '' + description: |- + "list_id" : "Returned if list_id is not a valid integer" + "" : "Returned if no valid recipient ids were passed" + "" : "Returned if no recipients were added" + "" : "Returned if request body is invalid JSON" schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: name - message: missing required argument + - field: list_id + message: list_id is invalid + - field: recipient_id + message: no valid recipients were provided + - field: null + message: no recipients were added + - field: null + message: request body is invalid JSON '401': description: '' schema: @@ -7971,830 +7902,1105 @@ paths: errors: - field: null message: authorization required - '403': - description: '' + '404': + description: '"list_id": "Returned if list_id does not exist"' schema: $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - field: null - message: Cannot create more than 100 API Keys + - field: list_id + message: list_id does not exist + - field: recipient_id + message: recipient_id does not exist security: - Authorization: [] - '/whitelabel/domains/{id}/validate': + '/contactdb/segments/{segment_id}': parameters: - - name: id + - name: segment_id in: path required: true type: string - post: - tags: - - Whitelabel - Domains - summary: Validate a domain whitelabel. + get: + summary: Retrieve a segment description: |- - **This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.** - - A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + **This endpoint allows you to retrieve a single segment with the given ID.** - For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - ## URI Parameters - | URI Parameter | Type | Description | - |---|---|---| - | id | integer |ID of the domain whitelabel to validate. | - operationId: POST_whitelabel-domains-id-validate + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: GET_contactdb-segments-segment_id consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: segment_id + in: query + description: The ID of the segment you want to request. + required: true + type: number responses: '200': description: '' schema: - type: object - properties: - id: - type: integer - description: The ID of the domain whitelabel. - valid: - type: boolean - description: Indicates if this is a valid whitelabel. - validation_resuts: - type: object - description: 'The individual DNS records that are checked when validating, including the reason for any invalid DNS records.' - properties: - mail_cname: - type: object - description: The CNAME record for the domain whitelabel. - properties: - valid: - type: boolean - description: Indicates if this DNS record is valid. - reason: - type: string - description: The reason this record is invalid. - dkim1: - type: object - description: A DNS record for this domain whitelabel. - properties: - valid: - type: boolean - description: Indicates if the DNS record is valid. - reason: - type: 'null' - dkim2: - type: object - description: A DNS record for this whitelabel. - properties: - valid: - type: boolean - description: Indicates if the DNS record is valid. - reason: - type: 'null' - spf: - type: object - description: The SPF record for the whitelabel. - properties: - valid: - type: boolean - description: Indicates if the SPF record is valid. - reason: - type: 'null' + $ref: '#/definitions/contactdb_segments' examples: application/json: id: 1 - valid: true - validation_resuts: - mail_cname: - valid: false - reason: Expected your MX record to be "mx.sendgrid.net" but found "example.com". - dkim1: - valid: true - reason: null - dkim2: - valid: true - reason: null - spf: - valid: true - reason: null + name: Last Name Miller + list_id: 4 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + recipient_count: 1 '400': - description: Unexpected error in API call. See HTTP response body for details. - schema: - type: object - '500': - description: '' + description: '"segment_id" : "Returned if segment_id is not valid"' schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - message: - type: string - description: A message explaining the reason for the error. - required: - - message + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - - message: internal error getting TXT - security: - - Authorization: [] - /devices/stats: - parameters: [] - get: - tags: - - Stats - Advanced Stats - summary: 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)." - operationId: GET_devices-stats - consumes: - - application/json - produces: - - application/json - parameters: - - name: end_date - in: query - description: The end date of the statistics to retrieve. Defaults to today. - required: false - type: string - - name: limit - in: query - description: How many results to include on each page. - required: false - type: integer - - name: offset - in: query - description: How many results to exclude. - required: false - type: integer - - name: aggregated_by - in: query - description: 'How to group the statistics. Must be either "day", "week", or "month".' - required: false - type: string - - name: start_date - in: query - description: The starting date of the statistics to retrieve. - required: true - type: string - responses: - '200': + - message: if segment_id is not valid + '401': description: '' schema: - type: array - items: - $ref: '#/definitions/advanced_stats_opens' + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '404': + description: '"segment_id" : "Returned if segment_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - - 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 + errors: + - message: segment_id not found security: - Authorization: [] - /scopes: - parameters: [] - get: - tags: - - API Key Permissions - summary: Retrieve a list of scopes for which this user has access. + delete: + summary: Delete a segment description: |- - **This endpoint returns a list of all scopes that this user has access to.** + **This endpoint allows you to delete a segment from your recipients database.** - 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). - operationId: GET_scopes + You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. + + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. + + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: DELETE_contactdb-segments-segment_id consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: delete_contacts + in: query + description: True to delete all contacts matching the segment in addition to deleting the segment + type: boolean + - name: body + in: body + schema: + type: 'null' responses: - '200': + '204': description: '' schema: - type: object - properties: - scopes: - type: array - description: The list of scopes for which this user has access. - uniqueItems: true - items: - type: string - required: - - scopes + type: 'null' + '400': + description: |- + "segment_id" : "Returned if segment_id is not valid" + "delete_contacts" : "Returned if delete_contacts is not a valid boolean" + schema: + $ref: '#/definitions/global:ErrorResponse' examples: application/json: - scopes: - - mail.send - - alerts.create - - alerts.read + errors: + - field: segment_id + message: Returned if segment_id is not valid + - field: delete_contacts + message: Returned if delete_contacts is not a valid boolean '401': description: '' schema: - 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 + $ref: '#/definitions/global:ErrorResponse' examples: application/json: errors: - field: null message: authorization required + '404': + description: '"segment_id" : "Returned if segment_id does not exist"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: segment_id + message: segment_id does not exist security: - Authorization: [] - /geo/stats: - parameters: [] - get: - tags: - - Stats - Advanced Stats - summary: Retrieve email statistics by country and state/province. + patch: + summary: Update a segment description: |- - **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** + **This endpoint allows you to update a segment.** - **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. + The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. - Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). - operationId: GET_geo-stats + For more information about segments in Marketing Campaigns, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/lists.html#-Create-a-Segment). + operationId: PATCH_contactdb-segments-segment_id consumes: - application/json produces: - application/json parameters: - - name: limit - in: query - description: How many results to include on each page. - required: false - type: integer - - name: offset - in: query - description: How many results to exclude. - required: false - type: integer - - name: aggregated_by - in: query - description: 'How you would like the statistics to be grouped. Must be either "day", "week", or "month".' - required: false - type: string - enum: - - day - - week - - month - - name: start_date - in: query - description: The starting date of the statistics to retrieve. Must be in format YYYY-MM-DD - required: true - type: string - - name: end_date - in: query - description: 'The end date of the statistics to retrieve. ' - required: false - type: string - default: The date the request is made. - - name: country + - name: segment_id in: query - description: The country you would like to see statistics for. Currently only supported for US and CA. - required: false + description: The ID of the segment you are updating. type: string - enum: - - US - - CA + - name: body + in: body + schema: + type: object + properties: + name: + type: string + list_id: + type: number + description: The list ID you would like this segment to be built from. + conditions: + type: array + description: The conditions by which this segment should be created. + items: + $ref: '#/definitions/contactdb_segments_conditions' + required: + - name + example: + name: The Millers + list_id: 5 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' responses: '200': description: '' schema: - type: array - items: - $ref: '#/definitions/advanced_stats_country' + $ref: '#/definitions/contactdb_segments' examples: application/json: - - date: '2015-10-11' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-12' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-13' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-14' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-15' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-16' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-17' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-18' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-19' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-20' - stats: - - type: province - name: TX - metrics: - clicks: 0 - opens: 0 - unique_clicks: 0 - unique_opens: 0 - - date: '2015-10-21' + id: 5 + name: The Millers + list_id: 5 + conditions: + - field: last_name + value: Miller + operator: eq + and_or: '' + recipient_count: 1 + '400': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - message: request body is not valid json + - message: invalid value is passed into one of the request body parameters + - segment_id: segment_id + message: segment id is not valid + - field: field + message: field and set value is not passed into the request body + - field: value + message: value and set value is not passed into the request body + - field: operator + message: operator and set value is not passed into the request body + - field: and_or + message: and_or is not set on more than one condition and less than all conditions + - field: and_or + message: and_or is set on all conditions + - field: and_or + message: and_or is set on the only condition passed + - field: and_or + message: and_or and set value is not passed into the request body + - field: list_id + message: the list_id is not valid + - field: name + message: the name is not valid + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + security: + - Authorization: [] + /clients/stats: + parameters: [] + get: + tags: + - Stats - Advanced Stats + summary: 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). + operationId: GET_clients-stats + consumes: + - application/json + produces: + - application/json + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + responses: + '200': + description: '' + schema: + type: array + items: + $ref: '#/definitions/advanced_stats_opens' + examples: + application/json: + - date: '2014-10-01' stats: - - type: province - name: TX - metrics: - clicks: 0 + - metrics: 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 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: opens: 0 - unique_clicks: 0 unique_opens: 0 - /whitelabel/domains: + name: Gmail + type: client + security: + - Authorization: [] + /whitelabel/links/default: + parameters: [] + get: + tags: + - Whitelabel - Links + summary: Retrieve a Default Link Whitelabel + description: |- + **This endpoint allows you to retrieve the default link whitelabel.** + + Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: +Something something unsubscribe <% %> something something
- landing: | -subscribehere
- plain_content: Something something unsubscribe <% %> something something - replace: thetag - url: '' - security: - - Authorization: [] - /tracking_settings: - parameters: [] - get: - summary: 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). - operationId: GET_tracking_settings - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: The number of settings to return. - type: integer - - name: offset - in: query - description: Where in the list of results you want to begin retrieving settings. - type: integer + type: 'null' responses: '200': description: '' schema: type: object properties: - result: - type: array - description: The list of all tracking settings. - items: - type: object - properties: - name: - type: string - description: The name of the event being tracked. - title: - type: string - description: The title of the tracking setting. - description: - type: string - description: A description about the event that is being tracked. - enabled: - type: boolean - description: Indicates if this tracking setting is currently enabled. - examples: - application/json: - result: - - name: open - title: Open Tracking - description: lorem ipsum... . - enabled: true - security: - - Authorization: [] - /tracking_settings/google_analytics: - parameters: [] - get: - summary: 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). - operationId: GET_tracking_settings-google_analytics - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - $ref: '#/definitions/google_analytics_settings' + id: + type: integer + description: The ID of the domain whitelabel. + valid: + type: boolean + description: Indicates if this is a valid whitelabel. + validation_resuts: + type: object + description: 'The individual DNS records that are checked when validating, including the reason for any invalid DNS records.' + properties: + mail_cname: + type: object + description: The CNAME record for the domain whitelabel. + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + reason: + type: string + description: The reason this record is invalid. + dkim1: + type: object + description: A DNS record for this domain whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + reason: + type: 'null' + dkim2: + type: object + description: A DNS record for this whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + reason: + type: 'null' + spf: + type: object + description: The SPF record for the whitelabel. + properties: + valid: + type: boolean + description: Indicates if the SPF record is valid. + reason: + type: 'null' examples: application/json: - enabled: true - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' - security: - - Authorization: [] - patch: - summary: 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). - operationId: PATCH_tracking_settings-google_analytics - consumes: - - application/json - produces: - - application/json - parameters: - - name: body - in: body - schema: - $ref: '#/definitions/google_analytics_settings' - example: - enabled: true - utm_source: sendgrid.com - utm_medium: email - utm_term: '' - utm_content: '' - utm_campaign: website - responses: - '200': + id: 1 + valid: true + validation_resuts: + mail_cname: + valid: false + reason: Expected your MX record to be "mx.sendgrid.net" but found "example.com". + dkim1: + valid: true + reason: null + dkim2: + valid: true + reason: null + spf: + valid: true + reason: null + '400': + description: Unexpected error in API call. See HTTP response body for details. + schema: + type: object + '500': description: '' schema: - $ref: '#/definitions/google_analytics_settings' + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + description: A message explaining the reason for the error. + required: + - message examples: application/json: - enabled: true - utm_campaign: '' - utm_content: lotsandlotsofcontent - utm_medium: '' - utm_source: '' - utm_term: '' + errors: + - message: internal error getting TXT security: - Authorization: [] - /tracking_settings/open: - parameters: [] - get: - summary: Get Open Tracking Settings + '/campaigns/{campaign_id}/schedules/now': + parameters: + - name: campaign_id + in: path + required: true + type: integer + post: + summary: Send a Campaign description: |- - **This endpoint allows you to retrieve your current settings for open tracking.** + **This endpoint allows you to immediately send a campaign at the time you make the API call.** - 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. + 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. - 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: - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: GET_tracking_settings-open + * [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) + operationId: POST_campaigns-campaign_id-schedules-now consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + type: 'null' responses: - '200': + '201': description: '' schema: + title: Send a Campaign response type: object properties: - enabled: - type: boolean - description: Indicates if open tracking is enabled. + id: + type: integer + format: int64 + status: + type: string required: - - enabled + - id + - status examples: application/json: - enabled: true + id: 1234 + status: Scheduled + '400': + description: |- + "subject": "subject can't be blank" + "sender_id": "sender_id can't be blank" + "plain_content": "plain_content can't be blank, please provide plain text or html content" + "list_ids": "You must select at least 1 segment or 1 list to send to." + "unsubscribe_tag": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." + "suppression_group_id": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." + "": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: subject + message: subject can't be blank + - field: sender_id + message: sender_id can't be blank + - field: plain_content + message: 'plain_content can''t be blank, please provide plain text or html content' + - field: list_id + message: You must select at least 1 segment or 1 list to send to. + - field: unsubscribe_tag + message: 'An [unsubscribe] tag in both your html and plain content is required to send a campaign.' + - field: suppression_group_id + message: Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign. + - field: null + message: 'You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing' + '401': + description: '' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: authorization required + '403': + description: '"": "You may only send a campaign when it is in draft mode."' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: You may only send a campaign when it is in draft mode. + '404': + description: '"": "not found"' + schema: + $ref: '#/definitions/global:ErrorResponse' + examples: + application/json: + errors: + - field: null + message: not found security: - Authorization: [] - patch: - summary: Update Open Tracking Settings + /whitelabel/domains: + parameters: [] + post: + tags: + - Whitelabel - Domains + summary: Create a domain whitelabel. description: |- - **This endpoint allows you to update your current settings for open tracking.** + **This endpoint allows you to create a whitelabel for one of your domains.** - 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. + If you are creating a domain whitelabel that you would like a subuser to use, you have two options: + 1. Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. + 2. Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. - You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - operationId: PATCH_tracking_settings-open + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: POST_whitelabel-domains consumes: - application/json produces: @@ -11338,36 +11545,89 @@ paths: schema: type: object properties: - enabled: + domain: + type: string + description: Domain being whitelabeled. + subdomain: + type: string + description: The subdomain to use for this domain whitelabel. + username: + type: string + description: The username that this whitelabel will be associated with. + ips: + type: array + description: The IP addresses that will be included in the custom SPF record for this whitelabel. + items: + type: string + custom_spf: type: boolean - description: The new status that you want to set for open tracking. + description: Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to domain whitelabels setup for manual security. + default: + type: boolean + description: Whether to use this whitelabel as the fallback if no domain whitelabels match the sender's domain. + automatic_security: + type: boolean + description: 'Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation.' + required: + - domain + - subdomain example: - enabled: true + domain: example.com + subdomain: news + username: john@example.com + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + automatic_security: false responses: - '200': + '201': description: '' schema: - type: object - properties: - enabled: - type: boolean - description: Indicates if open tracking is enabled. - required: - - enabled + $ref: '#/definitions/whitelabel::domain' examples: application/json: - enabled: true + id: 302183 + user_id: 1446226 + subdomain: example + domain: example.com + username: mbernier + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_cname: + valid: false + type: cname + host: example.example.com + data: u1446226.wl.sendgrid.net + dkim1: + valid: false + type: cname + host: s1._domainkey.example.com + data: s1.domainkey.u1446226.wl.sendgrid.net + dkim2: + valid: false + type: cname + host: s2._domainkey.example.com + data: s2.domainkey.u1446226.wl.sendgrid.net security: - Authorization: [] - /mail_settings: - parameters: [] get: - summary: Retrieve all mail settings - description: |- - **This endpoint allows you to retrieve a list of all mail settings.** + tags: + - Whitelabel - Domains + summary: List all domain whitelabels. + description: | + **This endpoint allows you to retrieve a list of all domain whitelabels you have created.** - Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). - operationId: GET_mail_settings + A domain whitelabel allows you to remove the “via” or “sent on behalf of” message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + + For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + operationId: GET_whitelabel-domains consumes: - application/json produces: @@ -11375,196 +11635,388 @@ paths: parameters: - name: limit in: query - description: The number of settings to return. + description: Number of domains to return. type: integer - name: offset in: query - description: Where in the list of results to begin displaying settings. + description: Paging offset. type: integer + - name: exclude_subusers + in: query + description: Exclude subuser domains from the result. + type: boolean + - name: username + in: query + description: The username associated with a whitelabel. + type: string + - name: domain + in: query + description: Search for domain whitelabels that match the given domain. + type: string responses: '200': description: '' schema: - type: object - properties: - result: - type: array - description: The list of all mail settings. - items: + type: array + items: + type: object + properties: + id: + type: number + description: The ID of the domain whitelabel. + user_id: + type: number + description: The ID of the user that this whitelabel will be associated with. + subdomain: + type: string + description: The subdomain created for this domain whitelabel. + domain: + type: string + description: The domain that this whitelabel was created for. + username: + type: string + description: The username that this whitelabel is associated with. + ips: + type: array + description: The IPs that will be included in the custom SPF record. + items: + type: string + custom_spf: + type: boolean + description: Indicates if this whitelabel has custom SPF. + default: + type: boolean + description: Indicates if this whitelabel has been set as the default whitelabel. + legacy: + type: boolean + description: Indicates if this is whitelabel was created with the legacy whitelabel tool. + automatic_security: + type: boolean + description: Indicates if this whitelabel uses automated security. + valid: + type: boolean + description: Indicates if this is a valid whitelabel or not. + dns: type: object + description: The DNS records for this whitelabel that are used for authenticating the sending domain. properties: - 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 + mail_server: + type: object + description: Designates which mail server is responsible for accepting messages from a domain. + properties: + valid: + type: boolean + description: Indicates if this is a valid DNS record with no conflicts. + type: + type: string + description: The type of DNS record. + host: + type: string + description: The domain sending the messages. + data: + type: string + description: The mail server responsible for accepting messages. + subdomain_spf: + type: object + description: The SPF record for the subdomain used to create this whitelabel. + properties: + valid: + type: boolean + description: Indicates if the SPF record is valid. + type: + type: string + description: The type of data in the SPF record. + host: + type: string + description: The domain that this SPF record will be used to authenticate. + data: + type: string + description: The SPF record. + dkim: + type: object + description: The DNS record used when creating the DKIM signature. + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + type: + type: string + description: The type of DNS record. + enum: + - cname + - mx + - txt + host: + type: string + description: The domain that these DNS records will be applied to. + format: hostname + data: + type: string + description: The DNS record. + required: + - id + - user_id + - subdomain + - domain + - username + - ips + - custom_spf + - default + - legacy + - automatic_security + - valid + - dns examples: application/json: - 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. + - id: 1 + domain: example.com + subdomain: mail + username: john@example.com + user_id: 7 + ips: + - 192.168.1.1 + - 192.168.1.2 + custom_spf: true + default: true + legacy: false + automatic_security: true + valid: true + dns: + mail_cname: + host: mail.example.com + type: cname + data: u7.wl.sendgrid.net + valid: true + spf: + host: example.com + type: txt + data: 'v=spf1 include:u7.wl.sendgrid.net -all' + valid: true + dkim1: + host: s1._domainkey.example.com + type: cname + data: s1._domainkey.u7.wl.sendgrid.net + valid: true + dkim2: + host: s2._domainkey.example.com + type: cname + data: s2._domainkey.u7.wl.sendgrid.net + valid: true + - id: 2 + domain: example2.com + subdomain: news + username: jane@example2.com + user_id: 8 + ips: [] + custom_spf: false + default: true + legacy: false + automatic_security: true + valid: false + dns: + mail_server: + host: news.example2.com + type: mx + data: sendgrid.net + valid: false + subdomain_spf: + host: news.example2.com + type: txt + data: 'v=spf1 include:sendgrid.net ~all' + valid: false + domain_spf: + host: example2.com + type: txt + data: 'v=spf1 include:news.example2.com -all' + valid: false + dkim: + host: example2.com + type: txt + data: k=rsa; t=s; p=publicKey + valid: false security: - Authorization: [] - '/ips/pools/{pool_name}': + '/clients/{client_type}/stats': parameters: - - name: pool_name + - name: client_type in: path - description: The name of the IP pool that you want to retrieve the IP addresses from. + description: 'Specifies the type of client to retrieve stats for. Must be either "phone", "tablet", "webmail", or "desktop".' required: true type: string + enum: + - phone + - tablet + - webmail + - desktop get: - summary: Retrieve all IPs in a specified pool. + summary: Retrieve stats by a specific client type. description: |- - **This endpoint allows you to list all of the IP addresses that are in a specific IP pool.** + **This endpoint allows you to retrieve your email statistics segmented by a specific client type.** - 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. + **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. - IP pools can only be used with whitelabeled IP addresses. + ## Available Client Types + - phone + - tablet + - webmail + - desktop - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: GET_ips-pools-pool_name + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: GET_clients-client_type-stats consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD. + required: false + type: string + - name: aggregated_by + in: query + description: 'How to group the statistics. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month responses: '200': description: '' schema: - type: object - properties: - pool_name: - type: string - description: The name of the IP pool. - maxLength: 64 - ips: - type: array - description: The list of IP addresses that belong to this IP pool. - items: - type: string - required: - - pool_name - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - items: - type: object - properties: - field: - type: string - description: The name of the error. - message: - type: string - description: A message explaining why the IP addresses could not be listed. + type: array + items: + $ref: '#/definitions/advanced_stats_opens' examples: application/json: - errors: - - field: error - message: Unable to locate specified IPs Pool + - date: '2014-10-01' + stats: + - metrics: + opens: 1 + unique_opens: 1 + name: Gmail + type: client + - date: '2014-10-02' + stats: + - metrics: + opens: 0 + unique_opens: 0 + name: Gmail + type: client security: - Authorization: [] - delete: - summary: Delete an IP pool. + /browsers/stats: + parameters: [] + get: + tags: + - Stats - Advanced Stats + summary: 'Retrieve email statistics by browser. ' 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. + **This endpoint allows you to retrieve your email statistics segmented by browser type.** - IP pools can only be used with whitelabeled IP addresses. + **We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints. - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: DELETE_ips-pools-pool_name + Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). + operationId: GET_browsers-stats consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: start_date + in: query + description: The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD. + required: true + type: string + - name: end_date + in: query + description: The end date of the statistics to retrieve. Defaults to today. + required: false + type: string + - name: limit + in: query + description: The number of results to include on each page. + required: false + type: string + - name: offset + in: query + description: The number of results to exclude. + required: false + type: string + - name: aggregated_by + in: query + description: 'How to group the stats. Must be either "day", "week", or "month".' + required: false + type: string + enum: + - day + - week + - month + - name: browsers + in: query + description: The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times. + required: false + type: string responses: - '204': - description: '' - schema: - type: object - '404': + '200': description: '' schema: - type: object - properties: - error: - type: string - description: An error explaining why the pool could not be deleted. + type: array + items: + $ref: '#/definitions/advanced_stats_clicks' examples: application/json: - error: Unable to locate specified IPs Pool + - date: '2014-10-01' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser + - date: '2014-10-02' + stats: + - metrics: + clicks: 0 + unique_clicks: 0 + name: Chrome + type: browser + - metrics: + clicks: 1 + unique_clicks: 1 + name: Firefox + type: browser security: - Authorization: [] - put: - summary: Update an IP pool’s name. + '/whitelabel/links/{id}/validate': + parameters: + - name: id + in: path + description: The id of the link whitelabel that you want to validate. + required: true + type: integer + post: + tags: + - Whitelabel - Links + summary: Validate a Link Whitelabel 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. + **This endpoint allows you to validate a link whitelabel.** - IP pools can only be used with whitelabeled IP addresses. + Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - operationId: PUT_ips-pools-pool_name + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). + operationId: POST_whitelabel-links-id-validate consumes: - application/json produces: @@ -11573,60 +12025,124 @@ paths: - name: body in: body schema: - type: object - properties: - name: - type: string - description: The new name for your IP pool. - maxLength: 64 - example: - name: new_pool_name + type: 'null' responses: '200': description: '' schema: - $ref: '#/definitions/ip_pool' + type: object + properties: + id: + type: integer + description: The id of the link whitelabel. + valid: + type: boolean + description: Indicates if the link whitelabel is valid. + enum: + - true + - false + validation_results: + type: object + description: The individual validations results for each of the DNS records associated with this link whitelabel. + required: + - domain_cname + properties: + domain_cname: + type: object + description: The DNS record generated for the sending domain used for this link whitelabel. + required: + - valid + - reason + properties: + valid: + type: boolean + description: Indicates if this DNS record is valid. + enum: + - true + - false + reason: + type: + - string + - 'null' + description: 'Null if the DNS record is valid. If the DNS record is invalid, this will explain why.' + owner_cname: + type: object + description: The DNS record created to verify the link whitelabel. + properties: + valid: + type: boolean + description: Indicates if the DNS record is valid. + enum: + - true + - false + reason: + type: + - 'null' + - string + description: 'Null if valid. If the DNS record is invalid, this will explain why.' + required: + - valid + - reason + required: + - id + - valid + - validation_results examples: application/json: - name: new_pool_name - '404': + id: 1 + valid: true + validation_results: + domain_cname: + valid: false + reason: Expected CNAME to match "sendgrid.net." but found "example.com.". + owner_cname: + valid: true + reason: null + '400': + description: Unexpected error in API call. See HTTP response body for details. + schema: + type: object + '500': description: '' schema: type: object properties: errors: type: array + description: The reasons why the validation failed. 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. + description: The reason why the link whitelabel could not be validated. + required: + - message + required: + - errors examples: application/json: errors: - - field: null - message: ip pool not found + - message: internal error getting CNAME security: - Authorization: [] - '/ips/pools/{pool_name}/ips': + '/whitelabel/ips/{id}/validate': parameters: - - name: pool_name + - name: id in: path - description: The name of the IP pool that you want to add an IP address to. required: true - type: string + type: integer post: - summary: Add an IP address to a pool + tags: + - Whitelabel - IPs + summary: Validate an IP whitelabel description: |- - **This endpoint allows you to add an IP address to an IP pool.** + **This endpoint allows you to validate an IP whitelabel.** - 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 IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - 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. - operationId: POST_ips-pools-pool_name-ips + For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). + operationId: POST_whitelabel-ips-id-validate consumes: - application/json produces: @@ -11635,305 +12151,148 @@ paths: - name: body in: body schema: - type: object - properties: - ip: - type: string - description: The IP address that you want to add to an IP pool. - example: - ip: 0.0.0.0 + type: 'null' responses: - '201': + '200': description: '' schema: type: object properties: - ip: - type: string - description: The IP address. - pools: - type: array - description: The list of IP pools that this IP address has been added to. - items: - type: string - start_date: + id: type: integer - description: A unix timestamp indicating when the warmup process began for the IP address. - warmup: + description: The id of the IP whitelabel. + valid: type: boolean - description: Indicates if the IP address is in warmup. - required: - - ip - - pools - - start_date - - warmup - examples: - application/json: - ip: 000.00.00.0 - pools: - - test1 - start_date: 1409616000 - warmup: true - '404': - description: '' - schema: - type: object - properties: - errors: - type: array - description: The error returned. - items: - type: object - properties: - field: - type: 'null' - message: - type: string - description: A message explaining why the IP address could not be added to the IP Pool. - examples: - application/json: - errors: - - field: null - message: resource not found - security: - - Authorization: [] - /ips: - parameters: [] - get: - tags: - - IP Addresses - summary: 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. - operationId: GET_ips - consumes: - - application/json - produces: - - application/json - parameters: - - name: ip - in: query - description: The IP address to get - type: string - - name: exclude_whitelabels - in: query - description: Should we exclude whitelabels? - type: boolean - - name: subuser - in: query - description: The subuser you are requesting for. - type: string - - name: limit - in: query - description: The number of IPs you want returned at the same time. - type: integer - default: 10 - - name: offset - in: query - description: The offset for the number of IPs that you are requesting. - type: integer - default: 0 - responses: - '200': - description: '' - schema: - type: array - items: - type: object - properties: - ip: - type: string - description: An IP address. - subusers: - type: array - description: The subusers that are able to send email from this IP. - items: - type: string - rdns: - type: string - description: The reverse DNS record for this IP address. - pools: - type: array - description: The IP pools that this IP has been added to. - items: - type: string - warmup: - type: boolean - description: Indicates if this IP address is currently warming up. - start_date: - type: - - number - - 'null' - description: The date that the IP address was entered into warmup. - whitelabeled: - type: boolean - description: Indicates if this IP address has been whitelabeled. - required: - - ip - - subusers - - pools - - warmup - - start_date - - whitelabeled - examples: - application/json: - - ip: 127.0.0.1 - subusers: - - example_subuser1 - - example_subuser2 - rdns: o1.em.example.com - pools: [] - warmup: true - start_date: 1250337600 - whitelabeled: true - - ip: 127.0.0.1 - subusers: [] - pools: [] - warmup: false - start_date: null - whitelabeled: false - security: - - Authorization: [] - '/ips/{ip_address}': - parameters: - - name: ip_address - in: path - description: The IP address you are retrieving the IP pools for. - required: true - type: string - get: - summary: 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. - operationId: GET_ips-ip_address - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' + description: Indicates if the IP whitelabel is valid. + enum: + - true + - false + validation_results: + type: object + description: The specific results of the validation. + properties: + a_record: + type: object + properties: + valid: + type: boolean + description: Indicates if the IP whitelabel could be validated. + enum: + - true + - false + reason: + type: + - 'null' + - string + description: The reason the IP whitelabel could not be validated. Is null if the whitelabel was validated. + required: + - valid + - reason + required: + - id + - valid + - validation_results + examples: + application/json: + id: 1 + valid: true + validation_results: + a_record: + valid: true + reason: null + '404': + description: Unexpected error in API call. See HTTP response body for details. schema: type: object properties: - ip: - type: string - description: The IP address. - subusers: + errors: type: array - description: The subusers that can send email using this IP address. + description: The error messages for the failed validation. items: - type: string - rdns: - type: string - description: The reverse DNS record for this IP address. - pools: + type: object + properties: + message: + type: string + description: A message describing why the IP could not be validated. + required: + - message + required: + - errors + examples: + application/json: + errors: + - message: Whitelabel ip not found. + '500': + description: '' + schema: + type: object + properties: + errors: type: array - description: The list of IP pools that this IP address belongs to. + description: The error messages for the failed validation. 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. + type: object + properties: + message: + type: string + description: A message describing why the IP whitelabel could not be validated. + required: + - message required: - - ip - - subusers - - rdns - - pools - - warmup - - start_date - - whitelabeled + - errors examples: application/json: - ip: 000.00.00.0 - subusers: - - subuser1 - - subuser2 - rdns: o1.em.example.com - pools: - - test1 - warmup: false - start_date: null - whitelabeled: true + errors: + - message: internal error getting rDNS security: - Authorization: [] - /user/settings/enforced_tls: + /user/webhooks/event/test: parameters: [] - patch: - summary: Update Enforced TLS settings + post: + tags: + - Webhooks + summary: 'Test Event Notification Settings ' description: |- - **This endpoint allows you to update your current Enforced TLS settings.** + **This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** - The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. + SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. - operationId: PATCH_user-settings-enforced_tls + Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + operationId: POST_user-webhooks-event-test consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: type: object properties: - require_tls: - type: boolean - description: 'Indicates if you want to require your recipients to support TLS. ' - require_valid_cert: - type: boolean - description: Indicates if you want to require your recipients to have a valid certificate. + url: + type: string + description: The URL where you would like the test notification to be sent. example: - require_tls: true - require_valid_cert: false + url: url responses: - '200': + '204': description: '' schema: type: object - properties: - require_tls: - type: boolean - description: Indicates if your recipients are required to support TLS. - require_valid_cert: - type: boolean - description: Indicates if your recipients are required to have a valid certificate. - required: - - require_tls - - require_valid_cert - examples: - application/json: - require_tls: true - require_valid_cert: false security: - Authorization: [] + /ips/warmup: + parameters: [] get: - summary: Retrieve current Enforced TLS settings. + tags: + - IP Warmup + summary: Retrieve all IPs currently in warmup description: |- - **This endpoint allows you to retrieve your current Enforced TLS settings.** + **This endpoint allows you to retrieve all of your IP addresses that are currently warming up.** - The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the [SMTP Ports User Guide](https://sendgrid.com/docs/Classroom/Basics/Email_Infrastructure/smtp_ports.html) for more information on opportunistic TLS. + 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. - **Note:** If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with “TLS required but not supported” as the description. - operationId: GET_user-settings-enforced_tls + For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). + operationId: GET_ips-warmup consumes: - application/json produces: @@ -11943,49 +12302,48 @@ paths: '200': description: '' schema: - type: object - properties: - require_tls: - type: boolean - description: Indicates if the recipient is required to support TLS. - require_valid_cert: - type: boolean - description: Indicates if the recipient is required to have a valid certificate. - required: - - require_tls - - require_valid_cert + $ref: '#/definitions/ip_warmup_response' examples: application/json: - require_tls: false - require_valid_cert: false + - ip: 0.0.0.0 + start_date: 1409616000 security: - Authorization: [] - '/ips/warmup/{ip_address}': - parameters: - - name: ip_address - in: path - description: The IP address that you want to remove from warmup mode. - required: true - type: string - delete: - summary: Remove an IP from warmup + post: + tags: + - IP Warmup + summary: Add an IP to warmup description: |- - **This endpoint allows you to remove an IP address from warmup mode.** + **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). - operationId: DELETE_ips-warmup-ip_address + operationId: POST_ips-warmup consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + ip: + type: string + description: The IP address that you want to begin warming up. + example: + ip: 0.0.0.0 responses: - '204': + '200': description: '' schema: - type: object + $ref: '#/definitions/ip_warmup_response' + examples: + application/json: + - ip: 0.0.0.0 + start_date: 1409616000 '404': description: '' schema: @@ -12001,7 +12359,7 @@ paths: type: 'null' message: type: string - description: A message explaining why the IP couldn't be removed from warmup. + description: A message explaining why the IP couldn't entered into warmup mode. examples: application/json: errors: @@ -12009,173 +12367,207 @@ paths: message: resource not found security: - Authorization: [] + /categories: + parameters: [] get: - summary: Retrieve warmup status for a specific IP address + tags: + - Categories + summary: Retrieve all categories 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. + **This endpoint allows you to retrieve a list of all of your categories.** - For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). - operationId: GET_ips-warmup-ip_address + 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). + operationId: GET_categories consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: limit + in: query + description: The number of categories to display per page. + type: integer + default: 50 + - name: category + in: query + description: Allows you to perform a prefix search on this particular category. + type: string + - name: offset + in: query + description: The point in the list that you would like to begin displaying results. + type: integer + default: 0 responses: '200': description: '' schema: - $ref: '#/definitions/ip_warmup_response' - '404': + type: array + items: + type: object + properties: + category: + type: string + description: A category used to group emails by broad topic. + required: + - category + examples: + application/json: + - category: category 1 + - category: category 2 + '400': description: '' schema: type: object properties: errors: type: array - description: The errors that were encountered. + description: The error returned. items: type: object properties: field: - type: 'null' + type: string message: type: string - description: A message explaining why the warmup status could not be retrieved. + description: A message explaining why your categories could not be retrieved. + required: + - field + - message examples: application/json: errors: - - field: null - message: resource not found + - field: sort_by + message: invalid sort value security: - Authorization: [] - /suppression/unsubscribes: + /user/webhooks/parse/settings: parameters: [] get: tags: - - Suppression Management - Global Suppressions - summary: Retrieve all global suppressions + - Webhooks + summary: Retrieve Parse Webhook settings description: |- - **This endpoint allows you to retrieve a list of all email address that are globally suppressed.** + **This endpoint allows you to retrieve your current inbound parse webhook settings.** - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: GET_suppression-unsubscribes + SendGrid can parse the attachments and contents of incoming emails. The Parse API will POST the parsed email to a URL that you specify. For more information, see our Inbound [Parse Webhook documentation](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). + operationId: GET_user-webhooks-parse-settings consumes: - application/json produces: - application/json - parameters: - - name: start_time - in: query - description: "\tRefers start of the time range in unix timestamp when an unsubscribe email was created (inclusive)." - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive). - type: integer - - name: limit - in: query - description: The number of results to display on each page. - type: integer - - name: offset - in: query - description: The point in the list of results to begin displaying global suppressions. - type: integer + parameters: [] responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the recipient was added to the global suppression list. - email: - type: string - description: The email address of the recipient who is globally suppressed. - required: - - created - - email + type: object + required: + - result + properties: + result: + type: array + description: The array containing the parse webhook settings. + items: + type: object + properties: + hostname: + type: string + description: The hostname of the URL where you would like your parsed emails to be posted. + url: + type: string + description: The URL where you want your parsed emails to be posted. + spam_check: + type: boolean + description: Indicates if the parsed content will be checked for spam. + send_raw: + type: boolean + description: Indicates if the raw content that was parsed will be posted. + required: + - hostname + - url + - spam_check + - send_raw examples: application/json: - - created: 1443651141 - email: user1@example.com - - created: 1443651154 - email: user2@example.com + result: + - hostname: example.com + url: 'http://example.com/example' + spam_check: false + send_raw: false security: - Authorization: [] - /asm/suppressions/global: + /tracking_settings: parameters: [] - post: - tags: - - Suppression Management - Global Suppressions - summary: Add recipient addresses to the global suppression group. + get: + summary: Retrieve Tracking Settings description: |- - **This endpoint allows you to add one or more email addresses to the global suppressions group.** + **This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** - A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). - operationId: POST_asm-suppressions-global + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings consumes: - application/json produces: - application/json parameters: - - name: body - in: body - schema: - type: object - properties: - recipient_emails: - type: array - description: 'The email address, or addresses, that you want to add to the global suppressions group.' - items: - type: string - example: - recipient_emails: - - test1@example.com - - test2@example.com + - name: limit + in: query + description: The number of settings to return. + type: integer + - name: offset + in: query + description: Where in the list of results you want to begin retrieving settings. + type: integer responses: - '201': + '200': description: '' schema: type: object properties: - recipient_emails: + result: type: array - description: The email addresses that are globally suppressed + description: The list of all tracking settings. items: - type: string - required: - - recipient_emails + type: object + properties: + name: + type: string + description: The name of the event being tracked. + title: + type: string + description: The title of the tracking setting. + description: + type: string + description: A description about the event that is being tracked. + enabled: + type: boolean + description: Indicates if this tracking setting is currently enabled. examples: application/json: - recipient_emails: - - test1@example.com - - test2@example.com + result: + - name: open + title: Open Tracking + description: lorem ipsum... . + enabled: true security: - Authorization: [] - '/suppression/blocks/{email}': - parameters: - - name: email - in: path - description: The email address of the specific block. - required: true - type: string + /tracking_settings/google_analytics: + parameters: [] get: - tags: - - Blocks API - summary: Retrieve a specific block + summary: Retrieve Google Analytics Settings description: |- - **This endpoint allows you to retrieve a specific email address from your blocks list.** + **This endpoint allows you to retrieve your current setting for Google Analytics.** - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + For more information about using Google Analytics, please refer to [Google’s URL Builder](https://support.google.com/analytics/answer/1033867?hl=en) and their article on ["Best Practices for Campaign Building"](https://support.google.com/analytics/answer/1037445). - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: GET_suppression-blocks-email + We default the settings to Google’s recommendations. For more information, see [Google Analytics Demystified](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/google_analytics_demystified_ga_statistics_vs_sg_statistics.html). + + You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: GET_tracking_settings-google_analytics consumes: - application/json produces: @@ -12185,361 +12577,524 @@ paths: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the block was created. - email: - type: string - description: The email address of the recipient that was blocked. - reason: - type: string - description: The reason why the email was blocked. - status: - type: string - description: The status of the block. - required: - - created - - email - - reason + $ref: '#/definitions/google_analytics_settings' examples: application/json: - - created: 1443651154 - email: user1@example.com - reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' - status: 4.0.0 + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' security: - Authorization: [] - delete: - tags: - - Blocks API - summary: Delete a specific block - description: |- - **This endpoint allows you to delete a specific email address from your blocks list.** - - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: DELETE_suppression-blocks-email - consumes: - - application/json - produces: [] - parameters: [] - responses: - '204': - description: '' - schema: - type: object - properties: {} - /suppression/blocks: - parameters: [] - delete: - tags: - - Blocks API - summary: Delete blocks + patch: + summary: Update Google Analytics Settings description: |- - **This endpoint allows you to delete all email addresses on your blocks list.** + **This endpoint allows you to update your current setting for Google Analytics.** - There are two options for deleting blocked emails: + 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). - 1. You can delete all blocked emails by setting `delete_all` to true in the request body. - 2. You can delete some blocked emails by specifying the email addresses in an array in the request body. + 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). - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + 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, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: DELETE_suppression-blocks + For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + operationId: PATCH_tracking_settings-google_analytics consumes: - application/json - produces: [] + produces: + - application/json parameters: - name: body in: body schema: - type: object - properties: - delete_all: - type: boolean - description: Indicates if you want to delete all blocked email addresses. - emails: - type: array - description: The specific blocked email addresses that you want to delete. - items: - type: string + $ref: '#/definitions/google_analytics_settings' example: - delete_all: false - emails: - - example1@example.com - - example2@example.com + enabled: true + utm_source: sendgrid.com + utm_medium: email + utm_term: '' + utm_content: '' + utm_campaign: website responses: - '204': + '200': description: '' schema: - type: object - properties: {} + $ref: '#/definitions/google_analytics_settings' + examples: + application/json: + enabled: true + utm_campaign: '' + utm_content: lotsandlotsofcontent + utm_medium: '' + utm_source: '' + utm_term: '' security: - Authorization: [] + /mail_settings: + parameters: [] get: - tags: - - Blocks API - summary: Retrieve all blocks + summary: Retrieve all mail settings description: |- - **This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.** - - [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + **This endpoint allows you to retrieve a list of all mail settings.** - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). - operationId: GET_suppression-blocks + Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrid’s [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). + operationId: GET_mail_settings consumes: - application/json produces: - application/json parameters: - - name: start_time - in: query - description: Refers start of the time range in unix timestamp when a blocked email was created (inclusive). - type: integer - - name: end_time - in: query - description: Refers end of the time range in unix timestamp when a blocked email was created (inclusive). - type: integer - name: limit in: query - description: Limit the number of results to be displayed per page. + description: The number of settings to return. type: integer - name: offset in: query - description: The point in the list to begin displaying results. + description: Where in the list of results to begin displaying settings. type: integer responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the blocks list. - email: - type: string - description: The email address that was added to the block list. - reason: - type: string - description: An explanation for the reason of the block. - status: - type: string - description: The status of the block. - required: - - created - - email - - reason - - status + type: object + properties: + result: + type: array + description: The list of all mail settings. + items: + type: object + properties: + title: + type: string + description: The title of the mail setting. + enabled: + type: boolean + description: Indicates if this mail setting is currently enabled. + name: + type: string + description: The name of the mail setting. + description: + type: string + description: A description of the mail setting. + required: + - title + - enabled + - name + - description + required: + - result examples: application/json: - - created: 1443651154 - email: user1@example.com - reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' - status: 4.0.0 + 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. security: - Authorization: [] - '/suppression/invalid_emails/{email}': + '/ips/pools/{pool_name}': parameters: - - name: email + - name: pool_name in: path - description: The invalid email address that you want to remove. + description: The name of the IP pool that you want to retrieve the IP addresses from. required: true type: string - delete: - summary: Delete a specific invalid email + get: + summary: Retrieve all IPs in a specified pool. description: |- - **This endpoint allows you to remove a specific email address from the invalid email address list.** + **This endpoint allows you to list all of the IP addresses that are in a specific IP pool.** - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + 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. - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + IP pools can only be used with whitelabeled IP addresses. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: DELETE_suppression-invalid_emails-email + If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + operationId: GET_ips-pools-pool_name consumes: - application/json - produces: [] + produces: + - application/json parameters: [] + responses: + '200': + description: '' + schema: + type: object + properties: + pool_name: + type: string + description: The name of the IP pool. + maxLength: 64 + ips: + type: array + description: The list of IP addresses that belong to this IP pool. + items: + type: string + required: + - pool_name + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: string + description: The name of the error. + message: + type: string + description: A message explaining why the IP addresses could not be listed. + examples: + application/json: + errors: + - field: error + message: Unable to locate specified IPs Pool + security: + - Authorization: [] + delete: + summary: 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. + operationId: DELETE_ips-pools-pool_name + consumes: + - application/json + produces: + - application/json + parameters: + - name: body + in: body + schema: + type: 'null' responses: '204': description: '' schema: type: object - properties: {} - get: - summary: Retrieve a specific invalid email + '404': + description: '' + schema: + type: object + properties: + error: + type: string + description: An error explaining why the pool could not be deleted. + examples: + application/json: + error: Unable to locate specified IPs Pool + security: + - Authorization: [] + put: + summary: Update an IP pool’s name. description: |- - **This endpoint allows you to retrieve a specific invalid email addresses.** + **This endpoint allows you to update the name of an IP pool.** - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + 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. - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + IP pools can only be used with whitelabeled IP addresses. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: GET_suppression-invalid_emails-email + If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + operationId: PUT_ips-pools-pool_name consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + name: + type: string + description: The new name for your IP pool. + maxLength: 64 + example: + name: new_pool_name responses: '200': description: '' schema: - type: array - items: - type: object - properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the invalid emails list. - email: - type: string - description: The email address that was marked as invalid. - reason: - type: string - description: A reason explaining why the email address was marked as invalid. - required: - - created - - email - - reason + $ref: '#/definitions/ip_pool' examples: application/json: - - created: 1454433146 - email: test1@example.com - reason: Mail domain mentioned in email address is unknown - /suppression/invalid_emails: + name: new_pool_name + '404': + description: '' + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the name of your IP pool could not be updated. + examples: + application/json: + errors: + - field: null + message: ip pool not found + security: + - Authorization: [] + /ips: parameters: [] get: - summary: Retrieve all invalid emails + tags: + - IP Addresses + summary: Retrieve all IP addresses description: |- - **This endpoint allows you to retrieve a list of all invalid email addresses.** - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: GET_suppression-invalid_emails + 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. + operationId: GET_ips consumes: - application/json produces: - application/json parameters: - - name: start_time + - name: ip in: query - description: Refers start of the time range in unix timestamp when an invalid email was created (inclusive). - type: integer - - name: end_time + description: The IP address to get + type: string + - name: exclude_whitelabels in: query - description: Refers end of the time range in unix timestamp when an invalid email was created (inclusive). - type: integer + description: Should we exclude whitelabels? + type: boolean + - name: subuser + in: query + description: The subuser you are requesting for. + type: string - name: limit in: query - description: Limit the number of results to be displayed per page. + description: The number of IPs you want returned at the same time. type: integer + default: 10 - name: offset in: query - description: Paging offset. The point in the list to begin displaying results. + description: The offset for the number of IPs that you are requesting. type: integer + default: 0 responses: '200': description: '' schema: type: array - description: The list of invalid email addresses. items: type: object properties: - created: - type: integer - description: A Unix timestamp indicating when the email address was added to the invalid emails list. - email: + ip: type: string - description: The email address that was marked as invalid. - reason: + 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 reason that the email address was marked as invalid. + 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: - - created - - email - - reason + - ip + - subusers + - pools + - warmup + - start_date + - whitelabeled examples: application/json: - - created: 1449953655 - email: user1@example.com - reason: Mail domain mentioned in email address is unknown - - created: 1449939373 - email: user1@example.com - reason: Mail domain mentioned in email address is unknown + - 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 security: - Authorization: [] + '/ips/warmup/{ip_address}': + parameters: + - name: ip_address + in: path + description: The IP address that you want to remove from warmup mode. + required: true + type: string delete: - summary: Delete invalid emails + summary: Remove an IP from warmup description: |- - **This endpoint allows you to remove email addresses from your invalid email address list.** - - There are two options for deleting invalid email addresses: - - 1) You can delete all invalid email addresses by setting `delete_all` to true in the request body. - 2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. - - An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. + **This endpoint allows you to remove an IP address from warmup mode.** - Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + 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 information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - operationId: DELETE_suppression-invalid_emails + For more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html). + operationId: DELETE_ips-warmup-ip_address consumes: - application/json - produces: [] + produces: + - application/json parameters: - name: body in: body + schema: + type: 'null' + responses: + '204': + description: '' + schema: + type: object + '404': + description: '' schema: type: object properties: - delete_all: - type: boolean - description: Indicates if you want to remove all email address from the invalid emails list. - emails: + errors: type: array - description: The list of specific email addresses that you want to remove. + description: The errors that were encountered. items: - type: string - example: - delete_all: false - emails: - - example1@example.com - - example2@example.com + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the IP couldn't be removed from warmup. + examples: + application/json: + errors: + - field: null + message: resource not found + security: + - Authorization: [] + get: + summary: 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). + operationId: GET_ips-warmup-ip_address + consumes: + - application/json + produces: + - application/json + parameters: [] responses: - '204': + '200': + description: '' + schema: + $ref: '#/definitions/ip_warmup_response' + '404': description: '' schema: type: object - properties: {} + properties: + errors: + type: array + description: The errors that were encountered. + items: + type: object + properties: + field: + type: 'null' + message: + type: string + description: A message explaining why the warmup status could not be retrieved. + examples: + application/json: + errors: + - field: null + message: resource not found security: - Authorization: [] - /suppression/spam_reports: + /suppression/unsubscribes: parameters: [] get: - summary: Retrieve all spam reports + tags: + - Suppression Management - Global Suppressions + summary: Retrieve all global suppressions description: |- - **This endpoint allows you to retrieve all spam reports.** - - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + **This endpoint allows you to retrieve a list of all email address that are globally suppressed.** - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: GET_suppression-spam_reports + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: GET_suppression-unsubscribes consumes: - application/json produces: @@ -12547,19 +13102,19 @@ paths: parameters: - name: start_time in: query - description: Refers start of the time range in unix timestamp when a spam report was created (inclusive). + description: Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive). type: integer - name: end_time in: query - description: Refers end of the time range in unix timestamp when a spam report was created (inclusive). + description: Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive). type: integer - name: limit in: query - description: Limit the number of results to be displayed per page. + description: The number of results to display on each page. type: integer - name: offset in: query - description: Paging offset. The point in the list to begin displaying results. + description: The point in the list of results to begin displaying global suppressions. type: integer responses: '200': @@ -12571,91 +13126,111 @@ paths: properties: created: type: integer - description: A Unix timestamp indicating when the spam report was made. + description: A Unix timestamp indicating when the recipient was added to the global suppression list. email: type: string - description: The email address of the recipient who marked your message as spam. - ip: - type: string - description: The IP address that the message was sent on. + description: The email address of the recipient who is globally suppressed. required: - created - email - - ip examples: application/json: - created: 1443651141 email: user1@example.com - ip: 10.63.202.100 - created: 1443651154 email: user2@example.com - ip: 10.63.202.100 security: - Authorization: [] - delete: - summary: Delete spam reports + /asm/suppressions/global: + parameters: [] + post: + tags: + - Suppression Management - Global Suppressions + summary: Add recipient addresses to the global suppression group. description: |- - **This endpoint allows you to delete your spam reports.** - - There are two options for deleting spam reports: - - 1) You can delete all spam reports by setting "delete_all" to true in the request body. - 2) You can delete some spam reports by specifying the email addresses in an array in the request body. - - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + **This endpoint allows you to add one or more email addresses to the global suppressions group.** - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: DELETE_suppression-spam_reports + A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). + operationId: POST_asm-suppressions-global consumes: - application/json - produces: [] + produces: + - application/json parameters: - name: body in: body schema: type: object properties: - delete_all: - type: boolean - description: Indicates if you want to delete all email addresses on the spam report list. - emails: + recipient_emails: type: array - description: A list of specific email addresses that you want to remove from the spam report list. + description: 'The email address, or addresses, that you want to add to the global suppressions group.' items: type: string example: - delete_all: false - emails: - - example1@example.com - - example2@example.com + recipient_emails: + - test1@example.com + - test2@example.com responses: - '204': + '201': description: '' schema: type: object - properties: {} + properties: + recipient_emails: + type: array + description: The email addresses that are globally suppressed + items: + type: string + required: + - recipient_emails + examples: + application/json: + recipient_emails: + - test1@example.com + - test2@example.com security: - Authorization: [] - '/suppression/spam_report/{email}': - parameters: - - name: email - in: path - description: The email address for the spam report that you want to delete. - required: true - type: string + /suppression/blocks: + parameters: [] delete: - summary: Delete a specific spam report + tags: + - Blocks API + summary: Delete blocks description: |- - **This endpoint allows you to delete a specific spam report.** + **This endpoint allows you to delete all email addresses on your blocks list.** - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + There are two options for deleting blocked emails: - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: DELETE_suppression-spam_report-email + 1. You can delete all blocked emails by setting `delete_all` to true in the request body. + 2. You can delete some blocked emails by specifying the email addresses in an array in the request body. + + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: DELETE_suppression-blocks consumes: - application/json produces: [] - parameters: [] + parameters: + - name: body + in: body + schema: + type: object + properties: + delete_all: + type: boolean + description: Indicates if you want to delete all blocked email addresses. + emails: + type: array + description: The specific blocked email addresses that you want to delete. + items: + type: string + example: + delete_all: false + emails: + - example1@example.com + - example2@example.com responses: '204': description: '' @@ -12665,19 +13240,37 @@ paths: security: - Authorization: [] get: - summary: Retrieve a specific spam report + tags: + - Blocks API + summary: Retrieve all blocks description: |- - **This endpoint allows you to retrieve a specific spam report.** + **This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.** - [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + [Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). - operationId: GET_suppression-spam_report-email + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + operationId: GET_suppression-blocks consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when a blocked email was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when a blocked email was created (inclusive). + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: The point in the list to begin displaying results. + type: integer responses: '200': description: '' @@ -12688,191 +13281,111 @@ paths: properties: created: type: integer - description: A Unix timestamp that indicates when the recipient marked your message as spam. + description: A Unix timestamp indicating when the email address was added to the blocks list. email: type: string - description: The email address of the recipient that marked your message as spam. - ip: + description: The email address that was added to the block list. + reason: type: string - description: The IP address that the message was sent from. + description: An explanation for the reason of the block. + status: + type: string + description: The status of the block. required: - created - email - - ip - examples: - application/json: - - created: 1454433146 - email: test1@example.com - ip: 10.89.32.5 - security: - - Authorization: [] - /access_settings/activity: - parameters: [] - get: - summary: 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). - operationId: GET_access_settings-activity - consumes: - - application/json - produces: - - application/json - parameters: - - name: limit - in: query - description: Limits the number of IPs to return. - type: integer - default: 20 - responses: - '200': - description: '' - schema: - type: object - properties: - result: - type: array - description: An array containing the IPs that recently attempted to access your account. - items: - type: object - properties: - allowed: - type: boolean - description: Indicates if the IP address was granted access to the account. - auth_method: - type: string - description: The authentication method used when attempting access. - first_at: - type: integer - description: A Unix timestamp indicating when the first access attempt was made. - ip: - type: string - description: The IP addressed used during the access attempt. - last_at: - type: integer - description: A Unix timestamp indicating when the most recent access attempt was made - location: - type: string - description: The geographic location from which the access attempt originated. - required: - - allowed - - auth_method - - first_at - - ip - - last_at - - location - required: - - result + - reason + - status examples: application/json: - 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' + - created: 1443651154 + email: user1@example.com + reason: 'error dialing remote address: dial tcp 10.57.152.165:25: no route to host' + status: 4.0.0 security: - Authorization: [] - '/access_settings/whitelist/{rule_id}': - parameters: - - name: rule_id - in: path - description: The ID of the whitelisted IP address that you want to retrieve. - required: true - type: string + /suppression/invalid_emails: + parameters: [] get: - summary: Retrieve a specific whitelisted IP + summary: Retrieve all invalid emails description: |- - **This endpoint allows you to retreive a specific IP address that has been whitelisted.** + **This endpoint allows you to retrieve a list of all invalid email addresses.** - You must include the ID for the specific IP address you want to retrieve in your call. + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - 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. + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: GET_access_settings-whitelist-rule_id + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: GET_suppression-invalid_emails consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when an invalid email was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when an invalid email was created (inclusive). + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: Paging offset. The point in the list to begin displaying results. + type: integer responses: '200': description: '' schema: - type: object - properties: - id: - type: integer - description: The ID of the IP address. - ip: - type: string - description: The IP address. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IP address was last updated. - required: - - id - - ip - - created_at - - updated_at + type: array + description: The list of invalid email addresses. + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the email address was added to the invalid emails list. + email: + type: string + description: The email address that was marked as invalid. + reason: + type: string + description: The reason that the email address was marked as invalid. + required: + - created + - email + - reason examples: application/json: - id: 1 - ip: 192.168.1.1 - created_at: 1441824715 - updated_at: 1441824715 + - created: 1449953655 + email: user1@example.com + reason: Mail domain mentioned in email address is unknown + - created: 1449939373 + email: user1@example.com + reason: Mail domain mentioned in email address is unknown security: - Authorization: [] delete: - summary: Remove a specific IP from the whitelist + summary: Delete invalid emails description: |- - **This endpoint allows you to remove a specific IP address from your IP whitelist.** - - When removing a specific IP address from your whitelist, you must include the ID in your call. + **This endpoint allows you to remove email addresses from your invalid email address list.** - 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. + There are two options for deleting invalid email addresses: - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: DELETE_access_settings-whitelist-rule_id - consumes: - - application/json - produces: [] - parameters: [] - responses: - '204': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] - /access_settings/whitelist: - parameters: [] - delete: - summary: Remove one or more IPs from the whitelist - description: |- - **This endpoint allows you to remove one or more IPs from your IP whitelist.** + 1) You can delete all invalid email addresses by setting `delete_all` to true in the request body. + 2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. - You can remove one IP at a time, or you can remove multiple IP addresses. + An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient’s mail server. - 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. + Examples include addresses without the “@” sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: DELETE_access_settings-whitelist + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + operationId: DELETE_suppression-invalid_emails consumes: - application/json produces: [] @@ -12882,16 +13395,19 @@ paths: schema: type: object properties: - ids: + delete_all: + type: boolean + description: Indicates if you want to remove all email address from the invalid emails list. + emails: type: array - description: An array of the IDs of the IP address that you want to remove from your whitelist. + description: The list of specific email addresses that you want to remove. items: - type: integer + type: string example: - ids: - - 1 - - 2 - - 3 + delete_all: false + emails: + - example1@example.com + - example2@example.com responses: '204': description: '' @@ -12900,395 +13416,295 @@ paths: properties: {} security: - Authorization: [] + /suppression/spam_reports: + parameters: [] get: - summary: Retrieve a list of currently whitelisted IPs + summary: Retrieve all spam reports description: |- - **This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted.** + **This endpoint allows you to retrieve all spam reports.** - 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. + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: GET_access_settings-whitelist + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: GET_suppression-spam_reports consumes: - application/json produces: - application/json - parameters: [] + parameters: + - name: start_time + in: query + description: Refers start of the time range in unix timestamp when a spam report was created (inclusive). + type: integer + - name: end_time + in: query + description: Refers end of the time range in unix timestamp when a spam report was created (inclusive). + type: integer + - name: limit + in: query + description: Limit the number of results to be displayed per page. + type: integer + - name: offset + in: query + description: Paging offset. The point in the list to begin displaying results. + type: integer responses: '200': description: '' schema: - type: object - properties: - result: - type: array - description: An array listing all of your whitelisted IPs. - items: - type: object - properties: - id: - type: integer - description: The ID of the whitelisted IP. - ip: - type: string - description: The whitelisted IP. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IPs whitelisting status was most recently updated. - required: - - id - - ip - - created_at - - updated_at - required: - - result + type: array + items: + type: object + properties: + created: + type: integer + description: A Unix timestamp indicating when the spam report was made. + email: + type: string + description: The email address of the recipient who marked your message as spam. + ip: + type: string + description: The IP address that the message was sent on. + required: + - created + - email + - ip examples: application/json: - 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 + - created: 1443651141 + email: user1@example.com + ip: 10.63.202.100 + - created: 1443651154 + email: user2@example.com + ip: 10.63.202.100 security: - - Authorization: [] - post: - summary: Add one or more IPs to the whitelist + - Authorization: [] + delete: + summary: Delete spam reports description: |- - **This endpoint allows you to add one or more IP addresses to your IP whitelist.** + **This endpoint allows you to delete your spam reports.** - 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. + There are two options for deleting spam reports: - 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. + 1) You can delete all spam reports by setting "delete_all" to true in the request body. + 2) You can delete some spam reports by specifying the email addresses in an array in the request body. - For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). - operationId: POST_access_settings-whitelist + [Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid. + + For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + operationId: DELETE_suppression-spam_reports consumes: - application/json - produces: - - application/json + produces: [] parameters: - name: body in: body schema: type: object properties: - ips: + delete_all: + type: boolean + description: Indicates if you want to delete all email addresses on the spam report list. + emails: type: array - description: An array containing the IP(s) you want to whitelist. + description: A list of specific email addresses that you want to remove from the spam report list. items: - type: object - properties: - ip: - type: string - description: An IP address that you want to whitelist. - required: - - ip - required: - - ips + type: string example: - ips: - - ip: 192.168.1.1 - - ip: 192.*.*.* - - ip: 192.168.1.3/32 + delete_all: false + emails: + - example1@example.com + - example2@example.com responses: - '201': + '204': description: '' schema: type: object - properties: - result: - type: array - description: An array listing all of your whitelisted IPs. - items: - type: object - properties: - id: - type: integer - description: The ID of the whitelisted IP. - ip: - type: string - description: The whitelisted IP. - created_at: - type: integer - description: A Unix timestamp indicating when the IP was whitelisted. - updated_at: - type: integer - description: A Unix timestamp indicating when the IPs whitelisting status was most recently updated. - required: - - id - - ip - - created_at - - updated_at - required: - - result - examples: - application/json: - result: - - id: 1 - ip: 192.168.1.1/32 - created_at: 1441824715 - updated_at: 1441824715 - - id: 2 - ip: 192.0.0.0/8 - created_at: 1441824715 - updated_at: 1441824715 - - id: 3 - ip: 192.168.1.3/32 - created_at: 1441824715 - updated_at: 1441824715 + properties: {} security: - Authorization: [] - /subusers/stats/monthly: + '/asm/groups/:group_id/suppressions': parameters: [] - get: - tags: - - Stats - Subuser Stats - summary: Retrieve monthly stats for all subusers + post: + summary: Search a suppression group for a set of email addresses description: |- - **This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: - `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`. + **This endpoint allows you to determine if the given list of email addresses exists in the given suppression group. The endpoint will return a subset of emails from the request that exists in the suppression group specified.** - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - operationId: GET_subusers-stats-monthly + Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses. + operationId: 'POST_asm-groups-:group_id-suppressions' consumes: - application/json produces: - application/json parameters: - - name: date - in: query - description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD - required: true - type: string - - name: subuser - in: query - description: A substring search of your subusers. - required: false - type: string - - name: sort_by_metric - in: query - description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.''' - required: false - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: limit - in: query - description: Optional field to limit the number of results returned. - required: false - type: integer - default: 5 - - name: offset - in: query - description: Optional beginning point in the list to retrieve from. - required: false - type: integer - default: 0 + - name: body + in: body + schema: + type: object + properties: + recipient_emails: + type: array + description: The list of email address you would like to search for. + items: + type: string + required: + - recipient_emails + example: + recipient_emails: + - exists1@example.com + - exists2@example.com + - doesnotexists@example.com responses: '200': description: '' schema: - $ref: '#/definitions/subuser_stats' + type: object + properties: + recipient_emails: + type: array + description: The subset of email address that do exist in the suppression group. + items: + type: string + required: + - recipient_emails examples: application/json: - date: '2016-02-01' - stats: - - first_name: John - last_name: Doe - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 0 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 1 - processed: 0 - requests: 100 - spam_report_drops: 0 - spam_reports: 99 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: user1 - type: subuser - - first_name: Jane - last_name: Doe - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 5 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 10 - processed: 10 - requests: 10 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: user2 - type: subuser + recipient_emails: + - exists1@example.com + - exists2@example.com security: - Authorization: [] - '/ips/pools/{pool_name}/ips/{ip}': + '/asm/suppressions/{email}': parameters: - - name: pool_name - in: path - description: The name of the IP pool that you are removing the IP address from. - required: true - type: string - - name: ip + - name: email in: path - description: The IP address that you are removing. + description: The email address that you want to search suppression groups for. required: true type: string - delete: - summary: Remove an IP address from a pool. + get: + tags: + - Suppression Management - Suppressions + summary: Retrieve all suppression groups for an email address description: |- - **This endpoint allows you to remove an IP address from an IP pool.** + **This endpoint will return a list of all suppression groups, indicating if the given email address is suppressed for each group.** - 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. - operationId: DELETE_ips-pools-pool_name-ips-ip + Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses. + operationId: GET_asm-suppressions-email consumes: - application/json produces: - application/json parameters: [] responses: - '204': - description: '' - schema: - type: object - '404': + '200': description: '' schema: type: object properties: - error: - type: string - description: An error explaining why the IP address could not be removed from the IP pool. - examples: - application/json: - error: Unable to locate specified IPs Pool - security: - - Authorization: [] - '/subusers/{subuser_name}/stats/monthly': - parameters: - - name: subuser_name - in: path - required: true - type: string + suppressions: + type: array + description: The array of suppression groups. + items: + type: object + properties: + description: + type: string + description: The description of the suppression group. + id: + type: integer + description: The id of the suppression group. + is_default: + type: boolean + description: Indicates if the suppression group is set as the default. + name: + type: string + description: The name of the suppression group. + suppressed: + type: boolean + description: Indicates if the given email address is suppressed for this group. + required: + - description + - id + - is_default + - name + - suppressed + required: + - suppressions + examples: + application/json: + suppressions: + - description: Optional description. + id: 1 + is_default: true + name: Weekly News + suppressed: true + - description: Some daily news. + id: 2 + is_default: true + name: Daily News + suppressed: true + - description: An old group. + id: 2 + is_default: false + name: Old News + suppressed: false + security: + - Authorization: [] + /asm/suppressions: + parameters: [] get: - summary: Retrieve the monthly email statistics for a single subuser + tags: + - Suppression Management - Suppressions + summary: Retrieve all suppressions description: |- - **This endpoint allows you to retrive the monthly email statistics for a specific subuser.** - - While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - - When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: - `bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`. + **This endpoint allows you to retrieve a list of all suppressions.** - For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - operationId: GET_subusers-subuser_name-stats-monthly + Suppressions are email addresses that can be added to [groups](https://sendgrid.com/docs/API_Reference/Web_API_v3/Suppression_Management/groups.html) to prevent certain types of emails from being delivered to those addresses. + operationId: GET_asm-suppressions consumes: - application/json produces: - application/json - parameters: - - name: date - in: query - description: The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD - required: true - type: string - - name: sort_by_metric - in: query - description: 'The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.''' - required: false - type: string - default: delivered - - name: sort_by_direction - in: query - description: The direction you want to sort. - required: false - type: string - default: desc - enum: - - desc - - asc - - name: limit - in: query - description: Optional field to limit the number of results returned. - required: false - type: number - default: 5 - - name: offset - in: query - description: Optional beginning point in the list to retrieve from. - required: false - type: integer - default: 0 + parameters: [] responses: '200': description: '' schema: - $ref: '#/definitions/subuser_stats' + type: array + items: + type: object + properties: + email: + type: string + description: The email address that was suppressed. + group_id: + type: integer + description: The id of the suppression group that this email address belongs to. + group_name: + type: string + description: The name of the suppression group that this email address belongs to. + created_at: + type: integer + description: A UNIX timestamp indicating when the suppression was created. + required: + - email + - group_id + - group_name + - created_at examples: application/json: - date: '2016-02-01' - stats: - - first_name: John - last_name: Doe - metrics: - blocks: 0 - bounce_drops: 0 - bounces: 0 - clicks: 5 - deferred: 0 - delivered: 0 - invalid_emails: 0 - opens: 10 - processed: 10 - requests: 10 - spam_report_drops: 0 - spam_reports: 0 - unique_clicks: 0 - unique_opens: 0 - unsubscribe_drops: 0 - unsubscribes: 0 - name: user1 - type: subuser + - email: test1@example.com + group_id: 1 + group_name: Weekly News + created_at: 1410986704 + - email: test1@example.com + group_id: 2 + group_name: Daily News + created_at: 1411493671 + - email: test2@example.com + group_id: 2 + group_name: Daily News + created_at: 1411493671 security: - Authorization: [] /user/email: @@ -13453,112 +13869,6 @@ paths: username: test_username security: - Authorization: [] - /user/credits: - parameters: [] - get: - tags: - - Users API - summary: Retrieve your credit balance - description: |- - **This endpoint allows you to retrieve the current credit balance for your account.** - - Your monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our [Clssroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html). - operationId: GET_user-credits - consumes: - - application/json - produces: - - application/json - parameters: [] - responses: - '200': - description: '' - schema: - type: object - properties: - remain: - type: integer - description: The remaining number of credits available on your account. - total: - type: integer - description: The total number of credits assigned to your account. - overage: - type: integer - description: The number of overdrawn credits for your account. - used: - type: integer - description: The number of credits that you have used. - last_reset: - type: string - description: The date that your credit balance was last reset. - next_reset: - type: string - description: The next date that your credit balance will be reset. - reset_frequency: - type: string - description: The frequency at which your credit balance will be reset. - required: - - remain - - total - - overage - - used - - last_reset - - next_reset - - reset_frequency - examples: - application/json: - remain: 200 - total: 200 - overage: 0 - used: 0 - last_reset: '2013-01-01' - next_reset: '2013-02-01' - reset_frequency: monthly - security: - - Authorization: [] - /user/password: - parameters: [] - put: - tags: - - Users API - summary: Update your password - description: |- - **This endpoint allows you to update your password.** - - Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - - For more information about your user profile: - - * [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) - operationId: PUT_user-password - consumes: - - application/json - produces: [] - parameters: - - name: body - in: body - schema: - type: object - properties: - new_password: - type: string - description: The new password you would like to use for your account. - old_password: - type: string - description: The old password for your account. - required: - - new_password - - old_password - example: - new_password: new_password - old_password: old_password - responses: - '200': - description: '' - schema: - type: object - properties: {} - security: - - Authorization: [] /mail/send/beta: parameters: [] post: @@ -13995,134 +14305,107 @@ paths: security: - Authorization: [] definitions: - monitor: - title: Create monitor settings request + suppression_group_unsubscribes: + allOf: + - $ref: '#/definitions/suppression_group' + - properties: + unsubscribes: + type: integer + description: The unsubscribes associated with this group. + required: + - unsubscribes 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 - example: - email: example@example.com - frequency: 50000 - contacts: + mail_settings_patch: type: object properties: - address: - type: string - address2: - type: object - city: - type: string - company: - type: string - country: - type: string + enabled: + type: boolean + description: Indicates if the mail setting is enabled. 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: + description: The email address of the recipient. + example: + enabled: true + email: email@example.com + 'global:empty_request': + type: 'null' + contactdb_recipient_count: + type: object + properties: + recipient_count: 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 + description: The count of recipients. required: - - disabled - - id - - username - - email + - recipient_count example: - disabled: false - email: example@example.com - id: 1234 - username: example_subuser - contactdb_segments_conditions: + recipient_count: 1234 + 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: - field: - type: string - value: - type: string - operator: + name: type: string - enum: - - eq - - ne - - lt - - gt - - contains - and_or: + description: The name of the field + type: type: string + description: The type of the field. enum: - - and - - or - - '' - required: - - field - - value - - operator - subuser_post: + - date + - text + - number + example: + name: first_name + type: text + contactdb_segments_with_id: + allOf: + - type: object + properties: + id: + type: number + description: The ID of the segment. + required: + - id + - $ref: '#/definitions/contactdb_segments' + transactional_template_version: type: object properties: - username: + template_id: type: string - description: The username of the subuser. - user_id: - type: number - description: The user ID for this subuser. - email: + description: The name of the 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: The email address for this subuser. - format: email - signup_session_token: + description: Name of the new transactional template version. + html_content: type: string - authorization_token: + description: The HTML content of the new version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content. + plain_content: type: string - credit_allocation: - type: object - properties: - type: - 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: - - username - - user_id - - email - example: - username: example_subuser - user_id: 1234 - email: example@example.com - signup_session_token: '' - authorization_token: '' - credit_allocation: - type: unlimited + - template_id + - active + - name + - html_content + - plain_content + - subject contactdb_segments: title: Create a Segment request type: object @@ -14161,369 +14444,582 @@ definitions: operator: eq and_or: or recipient_count: 1234 - campaign_request: + mail_batch_id: type: object properties: - title: + batch_id: 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. + pattern: '^[a-zA-Z0-9\-\_]' + required: + - batch_id + example: + batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi + campaign_response: + allOf: + - $ref: '#/definitions/campaign_request' + - type: object + properties: + status: + type: string + description: The status of your campaign. + id: + type: integer + required: + - status + 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 - 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. + example: + enabled: true + list: + - email1@example.com + - example.com + 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. + example: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + '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. + example: + enabled: false + html_content: | +<% body %>Example
+ mail_settings_forward_bounce: + type: object + properties: + email: type: - string - 'null' - description: The HTML of your marketing email. - plain_content: - type: - - string - - 'null' - description: The plain text content of your emails. + description: The email address that you would like your bounce reports forwarded to. + enabled: + type: boolean + description: Indicates if the bounce forwarding mail setting is enabled. + example: + enabled: false + email: null + mail_settings_forward_spam: + type: object + properties: + email: + type: string + description: The email address where you would like the spam reports to be forwarded. + enabled: + type: boolean + description: Indicates if the Forward Spam setting is enabled. + example: + email: '' + enabled: true + 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. + example: + email: example@example.com + enabled: false + 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: - - title + - id + - name + - recipient_count 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 - contactdb_recipient_response: + id: 1 + name: listname + recipient_count: 0 + user_profile: 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: + 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 + example: + address: '1451 Larimer Street, 3rd floor' + address2: '' + city: 'Denver, CO' + company: SendGrid + country: US + first_name: Matthew + last_name: Bernier + phone: '7208788003' + state: CO + website: 'http://sendgrid.com' + zip: '80202' + 'global:ErrorResponse': + type: object + properties: + errors: type: array - default: [] - description: The recipient IDs of the recipients that already existed from this request. items: - type: string - updated_count: - type: number - default: 0 - description: The recipients who were updated from this request. + type: object + properties: + field: + type: + - string + - 'null' + description: The field that generated the error. + message: + type: string + description: The error message. + required: + - message + example: errors: + - field: field_name + message: Some message here + 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 + example: + created: 1250337600 + email: example@example.com + reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ' + status: 5.1.1 + contactdb_recipient: + type: object + properties: + recipients: type: array items: type: object properties: - message: + id: type: string - error_indices: + 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: - type: number + $ref: '#/definitions/contactdb_custom_field_with_id_value' + email: + type: string + description: The email address of this recipient. This is a default custom field that SendGrid provides. + format: email + first_name: + type: + - string + - 'null' + description: The first name of this recipient. This is a default custom field that SendGrid provides. + last_name: + type: + - string + - 'null' + description: The last name of the recipient. + last_clicked: + type: + - number + - 'null' + description: 'The last time this recipient clicked a link from one of your campaigns, in unixtime.' + last_emailed: + type: + - number + - 'null' + description: 'The last time this user was emailed by one of your campaigns, in unixtime.' + last_opened: + type: + - number + - 'null' + description: 'The last time this recipient opened an email from you, in unixtime.' + updated_at: + type: number + description: The last update date for this recipient's record. + required: + - email + 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: - - error_count - - new_count - - persisted_recipients - - updated_count - example: - error_count: 1 - error_indices: - - 2 - new_count: 2 - persisted_recipients: - - YUBh - - bWlsbGVyQG1pbGxlci50ZXN0 - updated_count: 0 - errors: - - message: Invalid email. - error_indices: - - 2 - transactional_template_version: + - id + - name + 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: - template_id: - type: string - description: The name of the original transactional template. - active: + id: 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: + description: The id of the link whitelabel. + domain: type: string - description: Text/plain content of the new transactional template version. Must include <%body%> tag. Maximum of 1048576 bytes allowed for plain content. - subject: + description: The root domain for this link whitelabel. + subdomain: 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' - example: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - scopes: - - user.profile.read - - user.profile.update - credentials: - type: object - properties: - permissions: - type: object - properties: - api: - type: string - mail: - type: string - web: - 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 - example: - address: 1234 example street - address2: null - city: Denver - company: Company name - country: US - email: example@example.com - first_name: Example - last_name: User - phone: (555) 555-5555 - state: CO - zip: '55555' - partner_settings_new_relic: - type: object - properties: - enable_subuser_statistics: + 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 your subuser statistics will be sent to your New Relic Dashboard. - enabled: + description: Indicates if this is the default link whitelabel. + enum: + - true + - false + valid: 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: + description: Indicates if this link whitelabel is valid. + enum: + - true + - false + legacy: type: boolean - description: Indicates if the bounce forwarding mail setting is enabled. + 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 example: - enabled: false - email: null - api_key_name_id: + - ip: 0.0.0.0 + start_date: 1409616000 + ip_whitelabel: type: object properties: - api_key_id: + id: + type: integer + description: The id of the IP whitelabel. + ip: type: string - description: 'The ID of your API Key. ' - name: + description: The IP address that this whitelabel was created for. + rdns: type: string - description: The name of your API Key. - example: - api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA - name: A New Hope - '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: + 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 HTML content that you want to use for your legacy email template. - example: - enabled: false - html_content: | -<% body %>Example
- mail_settings_forward_spam: - type: object - properties: - email: + description: The subdomain created for this IP whitelabel. This is where the rDNS record points. + domain: type: string - description: The email address where you would like the spam reports to be forwarded. - enabled: + description: 'The root, or sending, domain.' + valid: type: boolean - description: Indicates if the Forward Spam setting is enabled. + 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 example: - email: '' - enabled: true - mail_settings_patch: + id: 1 + ip: 192.168.1.1 + rdns: o1.email.example.com + users: + - username: john@example.com + user_id: 7 + - username: jane@example.com + user_id: 8 + subdomain: email + domain: example.com + valid: true + legacy: false + a_record: + valid: true + type: a + host: o1.email.example.com + data: 192.168.1.1 + ip_pool: type: object properties: - enabled: - type: boolean - description: Indicates if the mail setting is enabled. - email: + name: type: string - description: The email address of the recipient. - example: - enabled: true - email: email@example.com - mail_settings_bcc: + description: The name of the IP pool. + maxLength: 64 + required: + - name + email_object: 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. - example: - email: example@example.com - enabled: false - 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 - example: - enabled: true - list: - - email1@example.com - - example.com - 'global:empty_request': - type: 'null' - mail_batch_id: - type: object - properties: - batch_id: + format: email + name: type: string - pattern: '^[a-zA-Z0-9\-\_]' + description: The name of the person to whom you are sending an email. required: - - batch_id - example: - batch_id: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi - 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' + - email contactdb_custom_field_with_id_value: allOf: - $ref: '#/definitions/contactdb_custom_field_with_id' @@ -14535,42 +15031,6 @@ definitions: - '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 - example: - name: first_name - type: text - contactdb_recipient_count: - type: object - properties: - recipient_count: - type: number - description: The count of recipients. - required: - - recipient_count - example: - recipient_count: 1234 user_scheduled_send_status: allOf: - $ref: '#/definitions/mail_batch_id' @@ -14585,158 +15045,329 @@ definitions: - pause required: - status - contactdb_list: - title: ContactDB lists + 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: integer - description: The reference ID of your list. - name: + type: number + description: The ID of this subuser. + username: type: string - description: The name of your list. - recipient_count: - type: integer - description: The count of recipients currently in the list. + 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 - - name - - recipient_count + - username + - email example: - id: 1 - name: listname - recipient_count: 0 - user_profile: + disabled: false + email: example@example.com + id: 1234 + username: example_subuser + contactdb_segments_conditions: type: object properties: - address: - type: string - address2: + field: type: string - city: + value: type: string - company: + operator: type: string - country: + enum: + - eq + - ne + - lt + - gt + - contains + and_or: type: string - first_name: + enum: + - and + - or + - '' + required: + - field + - value + - operator + subuser_post: + type: object + properties: + username: type: string - last_name: + description: The username of the subuser. + user_id: + type: number + description: The user ID for this subuser. + email: type: string - phone: + description: The email address for this subuser. + format: email + signup_session_token: type: string - state: + authorization_token: type: string - website: + credit_allocation: + type: object + properties: + type: + type: string + required: + - username + - user_id + - email + example: + username: example_subuser + user_id: 1234 + email: example@example.com + signup_session_token: '' + authorization_token: '' + credit_allocation: + type: unlimited + campaign_request: + type: object + properties: + title: type: string - zip: + description: The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI. + subject: + type: + - string + - 'null' + description: The subject of your campaign that your recipients will see. + sender_id: + type: + - 'null' + - integer + description: The ID of the "sender" identity that you have created. Your recipients will see this as the "from" on your marketing emails. + list_ids: + type: + - array + - 'null' + description: The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs + items: + type: integer + segment_ids: + type: + - array + - 'null' + description: The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. + items: + type: integer + categories: + type: + - array + - 'null' + description: The categories you would like associated to this campaign. + items: + type: string + suppression_group_id: + type: + - 'null' + - integer + description: 'The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type.' + custom_unsubscribe_url: + type: + - string + - 'null' + description: This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups. + ip_pool: + type: + - string + - 'null' + description: The pool of IPs that you would like to send this email from. + html_content: + type: + - string + - 'null' + description: The HTML of your marketing email. + plain_content: + type: + - string + - 'null' + description: The plain text content of your emails. + required: + - title + example: + id: 986724 + title: May Newsletter + subject: New Products for Summer! + sender_id: 124451 + list_ids: + - 110 + - 124 + segment_ids: + - 110 + categories: + - summer line + suppression_group_id: 42 + custom_unsubscribe_url: '' + ip_pool: marketing + html_content:Check out our summer line!
+ plain_content: Check out our summer line! + status: Draft + contactdb_recipient_response: + type: object + properties: + error_count: + type: number + default: 0 + description: The number of errors found while adding recipients. + error_indices: + type: array + default: [] + description: 'The indices of the recipient(s) sent that caused the error. ' + items: + type: number + new_count: + type: number + default: 0 + description: The count of new recipients added to the contactdb. + persisted_recipients: + type: array + default: [] + description: The recipient IDs of the recipients that already existed from this request. + items: + type: string + updated_count: + type: number + default: 0 + description: The recipients who were updated from this request. + errors: + type: array + items: + type: object + properties: + message: + type: string + error_indices: + type: array + items: + type: number + required: + - error_count + - new_count + - persisted_recipients + - updated_count + example: + error_count: 1 + error_indices: + - 2 + new_count: 2 + persisted_recipients: + - YUBh + - bWlsbGVyQG1pbGxlci50ZXN0 + updated_count: 0 + errors: + - message: Invalid email. + error_indices: + - 2 + 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' + example: + api_key_id: qfTQ6KG0QBiwWdJ0-pCLCA + name: A New Hope + scopes: + - user.profile.read + - user.profile.update + credentials: + type: object + properties: + permissions: + type: object + properties: + api: + type: string + mail: + type: string + web: + type: string + username: type: string example: - address: '1451 Larimer Street, 3rd floor' - address2: '' - city: 'Denver, CO' - company: SendGrid + address: 1234 example street + address2: null + city: Denver + company: Company name country: US - first_name: Matthew - last_name: Bernier - phone: '7208788003' + email: example@example.com + first_name: Example + last_name: User + phone: (555) 555-5555 state: CO - website: 'http://sendgrid.com' - zip: '80202' - 'global:ErrorResponse': + zip: '55555' + partner_settings_new_relic: 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 - example: - errors: - - field: field_name - message: Some message here - suppression_bounce: + 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 + monitor: + title: Create monitor settings request 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 + 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 example: - created: 1250337600 email: example@example.com - reason: '550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient''s email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ' - status: 5.1.1 - 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 + frequency: 50000 'whitelabel::domain': type: object properties: @@ -15001,135 +15632,33 @@ definitions: - 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 + - valid + - dns + 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: - - date - - stats - advanced_stats_clicks: + - id + - name + - description + advanced_stats_country: type: object properties: date: @@ -15152,14 +15681,22 @@ definitions: 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 @@ -15167,7 +15704,7 @@ definitions: required: - date - stats - advanced_stats_mailbox_provider: + advanced_stats_opens: type: object properties: date: @@ -15189,250 +15726,130 @@ definitions: 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 + - 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: - - 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 - example: - - ip: 0.0.0.0 - start_date: 1409616000 + - 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 category_stats: type: object properties: @@ -15563,93 +15980,6 @@ definitions: unsubscribes: 0 name: cat2 type: category - 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 - example: - id: 1 - ip: 192.168.1.1 - rdns: o1.email.example.com - users: - - username: john@example.com - user_id: 7 - - username: jane@example.com - user_id: 8 - subdomain: email - domain: example.com - valid: true - legacy: false - a_record: - valid: true - type: a - host: o1.email.example.com - data: 192.168.1.1 google_analytics_settings: type: object properties: @@ -15756,15 +16086,6 @@ definitions: enabled: false soft_bounces: 1234 hard_bounces: null - 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: @@ -15896,17 +16217,6 @@ definitions: 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: diff --git a/oai_stoplight.json b/oai_stoplight.json index 5131fc2..c53303e 100644 --- a/oai_stoplight.json +++ b/oai_stoplight.json @@ -3498,7 +3498,15 @@ ], "description": "**This endpoint allows you to remove a specific IP address from your IP whitelist.**\n\nWhen removing a specific IP address from your whitelist, you must include the ID in your call.\n\nIP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account.\n\nFor more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html).", "operationId": "DELETE_access_settings-whitelist-rule_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -3834,13 +3842,24 @@ ], "description": "**This endpoint allows you to revoke an existing API Key**\n\nAuthentications using this API Key will fail after this request is made, with some small propogation delay.If the API Key ID does not exist an HTTP 404 will be returned.\n\nThe API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html).\n\n## URI Parameters\n\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n|api_key_id |string | required | The ID of the API Key you are deleting.|", "operationId": "DELETE_api_keys-api_key_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], "responses": { "204": { "description": "", + "examples": { + "application/json": null + }, "schema": { "type": "null" } @@ -4169,9 +4188,16 @@ "consumes": [ "application/json" ], - "description": "**This endpoint allows you to retrieve a list of all suppression groups created by this user.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", + "description": "**This endpoint allows you to retrieve information about multiple suppression groups.**\n\nThis endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append `&id=` followed by the group ID.", "operationId": "GET_asm-groups", - "parameters": [], + "parameters": [ + { + "description": "The ID of a suppression group that you want to retrieve information for.", + "in": "query", + "name": "id", + "type": "integer" + } + ], "produces": [ "application/json" ], @@ -4181,26 +4207,26 @@ "examples": { "application/json": [ { - "description": "An Unsubscribe Group", - "id": 1234, + "description": "Our monthly newsletter.", + "id": 100, "is_default": true, "last_email_sent_at": null, - "name": "Unsubscribe Group", - "unsubscribes": 1234 + "name": "Newsletters", + "unsubscribes": 400 }, { - "description": "An Unsubscribe Group", - "id": 1234, - "is_default": true, + "description": "Emails triggered by user-defined rules.", + "id": 101, + "is_default": false, "last_email_sent_at": null, - "name": "Unsubscribe Group", - "unsubscribes": 1234 + "name": "Alerts", + "unsubscribes": 1 } ] }, "schema": { "items": { - "$ref": "#/definitions/suppression_group_unsubscribes" + "$ref": "#/definitions/suppression_group" }, "type": "array" } @@ -4211,7 +4237,7 @@ "Authorization": [] } ], - "summary": "Retrieve all suppression groups associated with the user.", + "summary": "Retrieve information about multiple suppression groups", "tags": [ "Suppression Management - Unsubscribe Groups" ], @@ -4232,7 +4258,7 @@ "consumes": [ "application/json" ], - "description": "**This endoint allows you to create a new suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", + "description": "**This endpoint allows you to create a new suppression group.**\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", "operationId": "POST_asm-groups", "parameters": [ { @@ -4240,23 +4266,22 @@ "name": "body", "schema": { "example": { - "description": "A group description", - "is_default": false, - "name": "A group name" + "description": "Suggestions for products our users might like.", + "is_default": true, + "name": "Product Suggestions" }, "properties": { "description": { - "description": "A description of the suppression group.", + "description": "A brief description of your new suppression group.", "maxLength": 100, "type": "string" }, "is_default": { - "default": false, - "description": "Indicates if this is the default suppression group.", + "description": "Indicates if you would like this to be your default suppression group.", "type": "boolean" }, "name": { - "description": "The name of the new suppression group. May not share its name with any other suppression group on the user.", + "description": "The name that you would like to use for your new suppression group.", "maxLength": 30, "type": "string" } @@ -4265,7 +4290,6 @@ "name", "description" ], - "title": "Create a Group request", "type": "object" } } @@ -4274,19 +4298,42 @@ "application/json" ], "responses": { - "200": { + "201": { "description": "", "examples": { "application/json": { - "description": "A group description", - "id": 1234, + "description": "Suggestions for products our users might like.", + "id": 103, "is_default": false, - "last_email_sent_at": null, - "name": "A group name" + "name": "Product Suggestions" } }, "schema": { - "$ref": "#/definitions/suppression_group" + "properties": { + "description": { + "description": "A brief description of the suppression group.", + "type": "string" + }, + "id": { + "description": "The ID of the suppression group.", + "type": "integer" + }, + "is_default": { + "description": "Indicates if this is the default suppression group.", + "type": "boolean" + }, + "name": { + "description": "The name of the suppression group.", + "type": "string" + } + }, + "required": [ + "id", + "name", + "description", + "is_default" + ], + "type": "object" } } }, @@ -4295,7 +4342,7 @@ "Authorization": [] } ], - "summary": "Create a Group", + "summary": "Create a new suppression group", "tags": [ "Suppression Management - Unsubscribe Groups" ], @@ -4305,8 +4352,8 @@ "id": "POST_asm-groups", "mock": { "dynamic": false, - "enabled": null, - "statusCode": null + "enabled": false, + "statusCode": 200 }, "public": true } @@ -4405,7 +4452,15 @@ ], "description": "**This endpoint allows you to delete a suppression group.**\n\nYou can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the \"one-click unsubscribe\" option on an email associated with a deleted group, that recipient will be added to the global suppression list.\n\nSuppression groups, or unsubscribe groups, are specific types or categories of email that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts.\n\nThe **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions.\n\nEach user can create up to 25 different suppression groups.", "operationId": "DELETE_asm-groups-group_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -4960,7 +5015,15 @@ ], "description": "**This endpoint allows you to remove an email address from the global suppressions group.**\n\nA global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html).", "operationId": "DELETE_asm-suppressions-global-email", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -5985,7 +6048,15 @@ ], "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).\n\nFor more information:\n\n* [User Guide > Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html)", "operationId": "DELETE_campaigns-campaign_id-schedules", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -7691,7 +7762,15 @@ ], "description": "**This endpoint allows you to delete a custom field by ID.**\n\nThe contactdb is a database of your contacts for [SendGrid Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html).", "operationId": "DELETE_contactdb-custom_fields-custom_field_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -9621,7 +9700,15 @@ ], "description": "**This endpoint allows you to delete a single recipient with the given ID from your contact database.**\n\nThe Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients.", "operationId": "DELETE_contactdb-recipients-recipient_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -10279,6 +10366,13 @@ "in": "query", "name": "delete_contacts", "type": "boolean" + }, + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } } ], "produces": [ @@ -12182,7 +12276,15 @@ ], "description": "**This endpoint allows you to delete an IP pool.**\n\nIP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic.\n\nIP pools can only be used with whitelabeled IP addresses.\n\nIf an IP pool is NOT specified for an email, it will use any IP available, including ones in pools.", "operationId": "DELETE_ips-pools-pool_name", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -12560,7 +12662,15 @@ ], "description": "**This endpoint allows you to remove an IP address from an IP pool.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "operationId": "DELETE_ips-pools-pool_name-ips-ip", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -12779,7 +12889,15 @@ ], "description": "**This endpoint allows you to remove an IP address from warmup mode.**\n\nSendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the [warmup schedule](https://sendgrid.com/docs/API_Reference/Web_API_v3/IP_Management/ip_warmup_schedule.html) for more details on how SendGrid limits your email traffic for IPs in warmup.\n\nFor more general information about warming up IPs, please see our [Classroom](https://sendgrid.com/docs/Classroom/Deliver/Delivery_Introduction/warming_up_ips.html).", "operationId": "DELETE_ips-warmup-ip_address", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -17301,7 +17419,15 @@ ], "description": "This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved.\n\nFor more information about Subusers:\n\n* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html)\n* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html)", "operationId": "DELETE_subusers-subuser_name", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -17553,7 +17679,15 @@ ], "description": "Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails.", "operationId": "DELETE_subusers-subuser_name-monitor", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -18164,7 +18298,15 @@ ], "description": "**This endpoint allows you to delete a specific email address from your blocks list.**\n\n[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html).", "operationId": "DELETE_suppression-blocks-email", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -18787,7 +18929,15 @@ ], "description": "**This endpoint allows you to remove a specific email address from the invalid email address list.**\n\nAn invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient\u2019s mail server.\n\nExamples include addresses without the \u201c@\u201d sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html).", "operationId": "DELETE_suppression-invalid_emails-email", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -18890,7 +19040,15 @@ ], "description": "**This endpoint allows you to delete a specific spam report.**\n\n[Spam reports](https://sendgrid.com/docs/Glossary/spam_reports.html) happen when a recipient indicates that they think your email is [spam](https://sendgrid.com/docs/Glossary/spam.html) and then their email provider reports this to SendGrid.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html).", "operationId": "DELETE_suppression-spam_report-email", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -19374,7 +19532,15 @@ ], "description": "**This endpoint allows you to delete a transactional template.**\n\nEach user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts.\n\nTransactional templates are templates created specifically for transactional email and are not to be confused with [Marketing Campaigns templates](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/templates.html). For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n", "operationId": "DELETE_templates-template_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -19607,7 +19773,15 @@ ], "description": "**This endpoint allows you to delete one of your transactional template versions.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "DELETE_templates-template_id-versions-version_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -19838,7 +20012,15 @@ ], "description": "**This endpoint allows you to activate a version of one of your templates.**\n\nEach transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates.\n\n\nFor more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html).\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| template_id | string | The ID of the original template |\n| version_id | string | The ID of the template version |", "operationId": "POST_templates-template_id-versions-version_id-activate", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -22930,7 +23112,15 @@ ], "description": "**This endpoint allows you to disassociate a specific whitelabel from a subuser.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nDomain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The the parent may then associate the whitelabel via the subuser management tools.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Required? | Description |\n|---|---|---|---|\n| username | string | required | Username for the subuser to find associated whitelabels for. |", "operationId": "DELETE_whitelabel-domains-subuser", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -23050,7 +23240,15 @@ ], "description": "**This endpoint allows you to delete a domain whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)", "operationId": "DELETE_whitelabel-domains-domain_id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -23411,7 +23609,15 @@ ], "description": "**This endpoint allows you to remove a domain's IP address from that domain's whitelabel.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer | ID of the domain whitelabel to delete the IP from. |\n| ip | string | IP to remove from the domain whitelabel. |", "operationId": "DELETE_whitelabel-domains-id-ips-ip", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -23515,7 +23721,15 @@ ], "description": "**This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated.**\n\nA domain whitelabel allows you to remove the \u201cvia\u201d or \u201csent on behalf of\u201d message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record.\n\nFor more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html)\n\n## URI Parameters\n| URI Parameter | Type | Description |\n|---|---|---|\n| id | integer |ID of the domain whitelabel to validate. |", "operationId": "POST_whitelabel-domains-id-validate", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -23894,7 +24108,15 @@ ], "description": "**This endpoint allows you to delete an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "DELETE_whitelabel-ips-id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -24080,7 +24302,15 @@ ], "description": "**This endpoint allows you to validate an IP whitelabel.**\n\nA IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html).", "operationId": "POST_whitelabel-ips-id-validate", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -24554,6 +24784,13 @@ "name": "username", "required": true, "type": "string" + }, + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } } ], "produces": [], @@ -24668,7 +24905,15 @@ ], "description": "**This endpoint allows you to delete a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "DELETE_whitelabel-links-id", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [], "responses": { "204": { @@ -24876,7 +25121,15 @@ ], "description": "**This endpoint allows you to validate a link whitelabel.**\n\nEmail link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net.\n\nFor more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html).", "operationId": "POST_whitelabel-links-id-validate", - "parameters": [], + "parameters": [ + { + "in": "body", + "name": "body", + "schema": { + "type": "null" + } + } + ], "produces": [ "application/json" ], @@ -25161,60 +25414,20 @@ "name": "Audit_LogDataInResponse", "script": "function(ctx, request, response) {\n /*\n This function is added to your calls if you want, by adding ?audit=true to your URI\n */\n\n var output = \"\";\n var spacer = \"\\t\";\n \n //fill in the date in the spreadsheet, so you don't have to\n var date = new Date();\n date.setHours(date.getHours() - 7); // time is UTC, so subtract 6 hrs to compensate to CT, 7 for MST\n var todays_date = date.toLocaleDateString(\"en-US\")+\"\\t\";\n \n //do we even snake case, bro?\n var regex_camel_case = new RegExp(\"^[a-zA-Z0-9_]*$\");\n \n //output += \"Limit: \" + response.header.get(\"X-RateLimit-Limit\") + \"//\";\n var checkHeader = function(header, test) {\n \n if (test) {\n return (response.header.get(header).indexOf(test) != -1 ? \"Yes\\t\" : \"No\\t\");\n } else {\n \n return (response.header.get(header) ? \"Yes\\t\" : \"No\\t\");\n }\n \n };\n \n \n \n \n var accept_header_block = \"DOES NOT INCLUDE ACCEPT HEADER BLOCK: \";\n\n //test the Accept header\n var code = response.statusCode.get();\n accept_header_block = (code == 406 ? \" \\tYes\\t \\tYes\\t\" : \"Yes\\tNo\\tYes\\tNo\\t\") + todays_date + spacer;\n \n \n \n var request_body_block = \"DOES NOT INCLUDE REQUEST BODY BLOCK: \";\n \n var req_body = response.body.get();\n var req_keys = Object.keys(req_body);\n \n var req_is_camel_case = 0, req_has_bool_vals = 0;\n\n for (var i=0; i