diff --git a/source/API_Reference/Web_API_v3/Settings/index.html b/source/API_Reference/Web_API_v3/Settings/index.html index e7b7285c17..ef66e68111 100644 --- a/source/API_Reference/Web_API_v3/Settings/index.html +++ b/source/API_Reference/Web_API_v3/Settings/index.html @@ -8,9 +8,21 @@ The v3 Settings API allows the user to set and check the status of user settings. +{% anchor h2 %} +V3 Settings +{% endanchor %} + + + {% anchor h2 %} V2 Settings {% endanchor %} + We have a bit of overlap between our v2 and v3 Settings APIs. As we roll out new endpoints we will update this page. - -{% anchor h2 %} -V3 Settings -{% endanchor %} - -Enforced TLS \ No newline at end of file diff --git a/source/API_Reference/Web_API_v3/Settings/mail.apiblueprint b/source/API_Reference/Web_API_v3/Settings/mail.apiblueprint new file mode 100644 index 0000000000..c5fb867882 --- /dev/null +++ b/source/API_Reference/Web_API_v3/Settings/mail.apiblueprint @@ -0,0 +1,394 @@ +--- +layout: page +title: Mail +weight: 0 +navigation: + show: true +seo: + title: Mail Settings API + description: Manage your mail sending settings via the SendGrid API. + keywords: mail settings, address whitelisting, bcc settings, bounce purge settings, event notification settings, footer settings, forward bounce settings, forward spam settings, legacy template settings +--- + +FORMAT: 1A + +# Mail Settings + +## Mail Settings Collection [/v3/mail_settings?limit={limit}&offset={offset}] + ++ Parameters + + limit (optional, number, `20`) ... Number of settings to return. + + offset (optional, number, `1`) ... Paging offset. + +### Get Mail Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "result": + [ + { + "name": "bcc", + "title": "BCC", + "description": "lorem ipsum... .", + "enabled": true + } + ] + } + + +## Address Whitelisting Settings [/v3/mail_settings/address_whitelist] + +### Get Address Whitelist Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "list": ["email1@example.com", "example.com"] + } + +### Update Address Whitelist Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "list": ["email1@example.com", "example.com"] + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "list": ["email1@example.com", "example.com"] + } + +## BCC Settings [/v3/mail_settings/bcc] + +### Get BCC Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "email": "email@example.com" + } + +### Update BCC Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "email": "email@example.com" + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "email": "email@example.com" + } + +## Bounce Purge Settings [/v3/mail_settings/bounce_purge] + + +### Get Bounce Purge Settings [GET] + +The number that is passed for both "hard_bounces" and "soft_bounces" must be a positive integer. + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "hard_bounces": 1, + "soft_bounces": 1 + } + +### Update Bounce Purge Settings [PATCH] + +The number that is passed for both "hard_bounces" and "soft_bounces" must be a positive integer. + ++ Request (application/json) + + + Body + + { + "enabled": true, + "hard_bounces": 1, + "soft_bounces": 1 + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "hard_bounces": 1, + "soft_bounces": 1 + } + +## Event Notification [/v3/user/webhooks/event/settings] + +### Get Event Notification Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "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 + } + +### Update Event Notification Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "url": "url", + "group_resubscribe": true, + "delivered": true, + "group_unsubscribe": true, + "spamreport": true, + "bounce": true, + "deferred": true, + "unsubscribe": true, + "processed": true, + "open": true, + "click": true, + "dropped": true + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "url": "url", + "group_resubscribe": true, + "delivered": true, + "group_unsubscribe": true, + "spamreport": true, + "bounce": true, + "deferred": true, + "unsubscribe": true, + "processed": true, + "open": true, + "click": true, + "dropped": true + } + +## Event Notification Test [/v3/user/webhooks/event/test] + +### Test Event Notification Settings [POST] +Sends a fake event notification post to the provided URL. + ++ Request (application/json) + + + Body + + { + "url": "url" + } + ++ Response 204 (application/json) + +## Footer Settings [/v3/mail_settings/footer] + +### Get Footer Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "html_content": "...", + "plain_content": "..." + } + +### Update Footer Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "html_content": "...", + "plain_content": "..." + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "html_content": "...", + "plain_content": "..." + } + +## Forward Bounce Settings [/v3/mail_settings/forward_bounce] + +### Get Forward Bounce Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "email": "email address" + } + +### Update Forward Bounce Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "email": "email address" + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "email": "email address" + } + +## Forward Spam Settings [/v3/mail_settings/forward_spam] + +### Get Forward Spam Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "email": "email address" + } + +### Update Forward Spam Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "email": "email address" + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "email": "email address" + } + +## Legacy Template Settings [/v3/mail_settings/template] + +### Get Template Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "html_content": "..." + } + +### Update Template Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "html_content": "..." + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "html_content": "..." + } + + +## Plain Content Settings [/v3/mail_settings/plain_content] + +### Get Plain Content Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true + } + +### Plain Text Content [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true + } \ No newline at end of file diff --git a/source/API_Reference/Web_API_v3/Settings/partners.apiblueprint b/source/API_Reference/Web_API_v3/Settings/partners.apiblueprint new file mode 100644 index 0000000000..794079fe52 --- /dev/null +++ b/source/API_Reference/Web_API_v3/Settings/partners.apiblueprint @@ -0,0 +1,106 @@ +--- +layout: page +title: Partner +weight: 0 +navigation: + show: true +breadcrumbs: true +seo: + title: Partner Settings API + keywords: partner settings api, New Relic settings, sendwithus settings + description: Manage SendGrid partner settings with the SendGrid API. +--- + +FORMAT: 1A + +# Group Partner Settings + +## Partner Settings Collection [/v3/partner_settings?limit={limit}&offset={offset}] + ++ Parameters + + limit (optional, number, `20`) ... Number of settings to return. + + offset (optional, number, `1`) ... Paging offset. + +### Get Partner Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "result": + [ + { + "name": "new_relic", + "title": "New Relic", + "description": "lorem ipsum... .", + "enabled": true + } + ] + } + +## New Relic Partner Settings Resource [/v3/partner_settings/new_relic] + +### Get New Relic Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "license_key": "key" + } + +### Update New Relic Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "license_key": "key" + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "license_key": "key" + } + +## SendWithUs Partner Settings Resource [/v3/partner_settings/sendwithus] + +### Get SendWithUs Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "license_key": "key" + } + +### Update SendWithUs Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "license_key": "key" + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "license_key": "key" + } \ No newline at end of file diff --git a/source/API_Reference/Web_API_v3/Settings/tracking.apiblueprint b/source/API_Reference/Web_API_v3/Settings/tracking.apiblueprint new file mode 100644 index 0000000000..3b9fc240a4 --- /dev/null +++ b/source/API_Reference/Web_API_v3/Settings/tracking.apiblueprint @@ -0,0 +1,190 @@ +--- +layout: page +title: Tracking +weight: 0 +navigation: + show: true +breadcrumbs: true +seo: + title: Tracking Settings API + keywords: tracking settings api, Click tracking settings, open tracking settings, unsubscribe tracking settings, google analytics settings + description: Manage your SendGrid tracking settings with the SendGrid API. +--- + +FORMAT: 1A + +# Group Tracking Settings + +## Tracking Settings Collection [/v3/tracking_settings?limit={limit}&offset={offset}] + ++ Parameters + + limit (optional, number, `20`) ... Number of settings to return. + + offset (optional, number, `1`) ... Paging offset. + +### Get Tracking Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "result": + [ + { + "name": "open", + "title": "Open Tracking", + "description": "lorem ipsum... .", + "enabled": true + } + ] + } + +## Click Tracking Settings Resource [/v3/tracking_settings/click] + +### Get Click Tracking Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true + } + +### Update Click Tracking Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true + } + +## Google Analytics Settings Resource [/v3/tracking_settings/google_analytics] + +### Get Google Analytics Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "utm_source":"sendgrid.com", + "utm_medium":"email", + "utm_term":"", + "utm_content":"", + "utm_campaign":"website" + } + +### Update Google Analytics Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "utm_source":"sendgrid.com", + "utm_medium":"email", + "utm_term":"", + "utm_content":"", + "utm_campaign":"website" + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "utm_source":"sendgrid.com", + "utm_medium":"email", + "utm_term":"", + "utm_content":"", + "utm_campaign":"website" + } + +## Open Tracking Settings Resource [/v3/tracking_settings/open] + +### Get Open Tracking Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true + } + +### Update Open Tracking Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true + } + +## Subscription Tracking Settings Resource [/v3/tracking_settings/subscription] + +### Get Subscription Tracking Settings [GET] + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content": "html content", + "plain_content": "text content" + } + +### Update Subscription Tracking Settings [PATCH] + ++ Request (application/json) + + + Body + + { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content": "html content", + "plain_content": "text content" + } + ++ Response 200 (application/json) + + + Body + + { + "enabled": true, + "landing": "landing page html", + "url": "url", + "replace": "replacement tag", + "html_content":"html content", + "plain_content":"text content" + } \ No newline at end of file diff --git a/source/API_Reference/Web_API_v3/Stats/advanced.md b/source/API_Reference/Web_API_v3/Stats/advanced.md index 4eefdb9030..6d810584c6 100644 --- a/source/API_Reference/Web_API_v3/Stats/advanced.md +++ b/source/API_Reference/Web_API_v3/Stats/advanced.md @@ -104,7 +104,7 @@ Available device types: {% parameter aggregated_by No 'Must be day|week|month' 'How to group the statistics' %} {% endparameters %} -{% apiv3example get GET https://api.sendgrid.com/v3/devices/stats?start_date=2015-01-01&end_date=2015-01-02 %} +{% apiv3example get GET https://api.sendgrid.com/v3/devices/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week %} {% v3response %} HTTP/1.1 200 [ @@ -152,7 +152,7 @@ Gets email statistics by client type. {% parameter aggregated_by No 'Must be day|week|month' 'How to group the statistics' %} {% endparameters %} -{% apiv3example get GET https://api.sendgrid.com/v3/clients/stats?start_date=2015-01-01&end_date=2015-01-02 %} +{% apiv3example get GET https://api.sendgrid.com/v3/clients/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week %} {% v3response %} HTTP/1.1 200 [ @@ -201,7 +201,7 @@ Gets email statistics for a single client type. {% parameter aggregated_by No 'Must be day|week|month' 'How to group the statistics' %} {% endparameters %} -{% apiv3example get GET https://api.sendgrid.com/v3/clients/:client_type/stats?start_date=2015-01-01&end_date=2015-01-02 %} +{% apiv3example get GET https://api.sendgrid.com/v3/clients/:client_type/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week %} {% v3response %} HTTP/1.1 200 [ @@ -306,7 +306,7 @@ HTTP/1.1 200 GET {% endanchor %} -Gets email statistics by browser. +Gets email statistics by browser. You can add multiple browsers to the URL, by using the `browsers` parameter multiple times. {% parameters get %} {% parameter start_date Yes 'Date formatted as YYYY-MM-DD' 'The starting date of the statistics to retrieve' %} @@ -315,7 +315,7 @@ Gets email statistics by browser. {% parameter browsers No 'Array of strings' 'The browsers to get statistics for, up to 10' %} {% endparameters %} -{% apiv3example get GET https://api.sendgrid.com/v3/browsers/stats?start_date=2015-01-01&end_date=2015-01-02 %} +{% apiv3example get GET https://api.sendgrid.com/v3/browsers/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week %} {% v3response %} HTTP/1.1 200 [ diff --git a/source/API_Reference/Web_API_v3/Stats/categories.md b/source/API_Reference/Web_API_v3/Stats/categories.md index 1cded3e1ea..b63ed96af0 100644 --- a/source/API_Reference/Web_API_v3/Stats/categories.md +++ b/source/API_Reference/Web_API_v3/Stats/categories.md @@ -12,7 +12,7 @@ Category Stats provide all of your user's email statistics for your categories. GET {% endanchor %} -Gets email statistics for the given categories. +Gets email statistics for the given categories. If you don't pass any parameters, the endpoint will return a sum for each category 10 at a time. {% parameters get %} {% parameter start_date Yes 'Date formatted as YYYY-MM-DD' 'The starting date of the statistics to retrieve' %} @@ -133,19 +133,19 @@ HTTP/1.1 200 GET {% endanchor %} -Gets the total sums of each email statistic metric for all categories over the -given date range. +Gets the total sums of each email statistic metric for all categories over the given date range. {% parameters get %} {% parameter start_date Yes 'Date formatted as YYYY-MM-DD' 'The starting date of the statistics to retrieve' %} {% parameter end_date No 'Date formatted as YYYY-MM-DD' 'The end date of the statistics to retrieve. Defaults to today.' %} - {% parameter sort_by_metric No 'A single metric' 'The metric that you want to sort by. Defaults to delivered.' %} + {% parameter aggregate_by No 'Date formatted as YYYY-MM-DD' 'The end date of the statistics to retrieve. Defaults to today.' %} + {% parameter sort_by_metric No 'A single metric' 'The metric that you want to sort by. Defaults to delivered.' %} {% parameter sort_by_direction No '[desc|asc]' 'The direction you want to sort. Defaults to desc.' %} {% parameter limit No 'Some integer.' 'Optional field to limit the number of results returned. Defaults to 5.' %} {% parameter offset No 'Some integer.' 'Optional beginning point in the list to retrieve from. Defaults to 0.' %} {% endparameters %} -{% apiv3example get GET https://api.sendgrid.com/v3/categories/stats/sums?start_date=2015-01-01&end_date=2015-01-02 %} +{% apiv3example get GET /v3/categories/stats/sums?start_date={start_date}&end_date={end_date}&aggregated_by={aggregated_by}&sort_by_metric={sort_by_metric}&sort_by_direction={sort_by_direction}&limit={limit}&offset={offset} %} {% v3response %} HTTP/1.1 200 { @@ -264,4 +264,4 @@ HTTP/1.1 200 ] } {% endv3response %} -{% endapiv3example %} \ No newline at end of file +{% endapiv3example %} diff --git a/source/API_Reference/Web_API_v3/Stats/parse.md b/source/API_Reference/Web_API_v3/Stats/parse.md index 90756d0934..d8b45f88d6 100644 --- a/source/API_Reference/Web_API_v3/Stats/parse.md +++ b/source/API_Reference/Web_API_v3/Stats/parse.md @@ -20,7 +20,7 @@ Gets statistics for Parse Webhook usage. {% parameter aggregated_by No 'Must be day|week|month' 'How to group the statistics' %} {% endparameters %} -{% apiv3example get GET https://api.sendgrid.com/v3/user/webhooks/parse/stats?start_date=2015-01-01&end_date=2015-01-02 %} +{% apiv3example get GET https://api.sendgrid.com/v3/user/webhooks/parse/stats?start_date=2015-01-01&end_date=2015-01-02&aggregated_by=week %} {% v3response %} [ { diff --git a/source/API_Reference/Web_API_v3/Stats/subusers.md b/source/API_Reference/Web_API_v3/Stats/subusers.md index 472c5eb310..8e0f983eac 100644 --- a/source/API_Reference/Web_API_v3/Stats/subusers.md +++ b/source/API_Reference/Web_API_v3/Stats/subusers.md @@ -12,7 +12,7 @@ Subuser Stats provide all of your user's email statistics for your subuser accou GET {% endanchor %} -Gets email statistics for the given subusers. +Gets email statistics for the given subusers. You can add up to 10 `subusers` parameters, one for each subuser you want stats for. {% parameters get %} {% parameter start_date Yes 'Date formatted as YYYY-MM-DD' 'The starting date of the statistics to retrieve' %} @@ -21,7 +21,7 @@ Gets email statistics for the given subusers. {% parameter subusers Yes 'Array of strings' 'The subusers to get statistics for, up to 10' %} {% endparameters %} -{% apiv3example get GET https://api.sendgrid.com/v3/subusers/stats?start_date=2015-01-01&end_date=2015-01-02&subusers=user1&subusers=user2 %} +{% apiv3example get GET /v3/subusers/stats?subusers={subusers}&subusers={subusers}&start_date={start_date}&end_date={end_date}&aggregated_by={aggregated_by} %} {% v3response %} HTTP/1.1 200 [ @@ -138,8 +138,10 @@ Gets the total sums of each email statistic metric for all subusers over the giv {% parameters get %} {% parameter start_date Yes 'Date formatted as YYYY-MM-DD' 'The starting date of the statistics to retrieve' %} {% parameter end_date No 'Date formatted as YYYY-MM-DD' 'The end date of the statistics to retrieve. Defaults to today.' %} + {% parameter aggregated_by No 'Must be day|week|month' 'How to group the statistics' %} {% parameter sort_by_metric No 'A single metric' 'The metric that you want to sort by. Defaults to delivered.' %} {% parameter sort_by_direction No '[desc|asc]' 'The direction you want to sort. Defaults to desc.' %} + {% parameter subusers Yes 'Array of strings' 'The subusers to get statistics for, up to 10' %} {% parameter limit No 'Some integer.' 'Optional field to limit the number of results returned. Defaults to 5.' %} {% parameter offset No 'Some integer.' 'Optional beginning point in the list to retrieve from. Defaults to 0.' %} {% endparameters %} @@ -263,4 +265,4 @@ HTTP/1.1 200 ] } {% endv3response %} -{% endapiv3example %} \ No newline at end of file +{% endapiv3example %} diff --git a/source/API_Reference/Web_API_v3/index.md b/source/API_Reference/Web_API_v3/index.md index 706557fde0..8b48053180 100644 --- a/source/API_Reference/Web_API_v3/index.md +++ b/source/API_Reference/Web_API_v3/index.md @@ -45,8 +45,8 @@ Host The host for API requests is `https://api.sendgrid.com/v3/` -{% info %} -All requests must be made over HTTPS. HTTP is **not** supported. +{% info %} +All requests must be made over HTTPS. HTTP is **not** supported. {% endinfo %} * * * * * @@ -58,7 +58,7 @@ Rate Limits All calls within the Web API are allotted a specific number of requests per refresh period. -Each Web API request returns the following header information +Each Web API request returns the following header information regarding rate limits and number of requests left. Depending on the endpoint you are trying to reach, it will have a @@ -72,13 +72,13 @@ GET https://api.sendgrid.com/v3/resource HTTP/1.1 Example Response {% codeblock lang:http %} -HTTP/1.1 200 OK -Content-Type: application/json +HTTP/1.1 200 OK +Content-Type: application/json X-RateLimit-Limit: 500 -X-RateLimit-Remaining: 499 +X-RateLimit-Remaining: 499 X-RateLimit-Reset: 1392815263 -{ +{ "foo": "bar" } {% endcodeblock %} @@ -103,13 +103,13 @@ X-RateLimit-Limit: 150 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1392815263 -{ +{ "errors": [ - { + { "field": null, "message": "too many requests" - }, - ] + }, + ] } {% endcodeblock %} @@ -131,7 +131,7 @@ Accept Header {% endanchor %} The API provides JSON responses. The [accept header](http://www.soapui.org/Best-Practices/understanding-rest-headers-and-parameters.html) is not currently -required, though it may be required in the future. If not set, the +required, though it may be required in the future. If not set, the API will use `application/json`. {% codeblock lang:http %} @@ -139,6 +139,18 @@ GET https://api.sendgrid.com/v3/endpoint HTTP/1.1 Accept: application/json {% endcodeblock %} +{% anchor h3 %} +Arrays of Data +{% endanchor %} + +When you send an array of data in a `GET` request, you will include the parameter multiple times on the URL. We do not require that you add brackets to the parameter name. + +Example Array in a GET request + +{% codeblock lang:http %} +GET https://api.sendgrid.com/v3/endpoint?parameter=data1¶meter=data2 HTTP/1.1 +{% endcodeblock %} + {% anchor h3 %} HTTP Verbs {% endanchor %} @@ -252,7 +264,7 @@ GET https://api.sendgrid.com/v3/resource?email=foo&bar=baz HTTP/1.1 Responses {% endanchor %} -{% anchor h3 %} +{% anchor h3 %} Content-Type Header {% endanchor %} @@ -308,7 +320,7 @@ support against resources. 500Internal server error - + * * * * * {% anchor h3 %} @@ -380,8 +392,8 @@ GET https://api.sendgrid.com/v3/resource?limit=5&offset=0 HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/json -Link: ; rel="next"; title="2", - ; rel="prev"; title="1", - ; rel="last"; title="3", +Link: ; rel="next"; title="2", + ; rel="prev"; title="1", + ; rel="last"; title="3", ; rel="first"; title="1" {% endcodeblock %}