diff --git a/packages/client/USAGE.md b/packages/client/USAGE.md index 87aff0fac..4588155df 100644 --- a/packages/client/USAGE.md +++ b/packages/client/USAGE.md @@ -28,6 +28,7 @@ client.setApiKey(process.env.SENDGRID_API_KEY); * [PARTNER SETTINGS](#partner-settings) * [SCOPES](#scopes) * [SENDERS](#senders) +* [SENDER AUTHENTICATION](#sender-authentication) * [STATS](#stats) * [SUBUSERS](#subusers) * [SUPPRESSION](#suppression) @@ -35,7 +36,6 @@ client.setApiKey(process.env.SENDGRID_API_KEY); * [TEMPLATES](#templates) * [TRACKING SETTINGS](#tracking-settings) * [USER](#user) -* [WHITELABEL](#whitelabel) @@ -2210,7 +2210,7 @@ This endpoint is for adding a(n) IP Address(es) to your account. **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** -The response includes warm-up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. +The response includes warm-up status, pools, assigned subusers, and authentication 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 to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. @@ -2261,7 +2261,7 @@ A single IP address or a range of IP addresses may be dedicated to an account to IP Pools allow you to group your dedicated SendGrid IP addresses. 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. +IP pools can only be used with authenticated IP addresses. If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. @@ -2287,7 +2287,7 @@ If an IP pool is NOT specified for an email, it will use any IP available, inclu IP Pools allow you to group your dedicated SendGrid IP addresses. 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. +IP pools can only be used with authenticated IP addresses. If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. @@ -2309,7 +2309,7 @@ If an IP pool is NOT specified for an email, it will use any IP available, inclu IP Pools allow you to group your dedicated SendGrid IP addresses. 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. +IP pools can only be used with authenticated IP addresses. If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. @@ -2335,7 +2335,7 @@ If an IP pool is NOT specified for an email, it will use any IP available, inclu IP Pools allow you to group your dedicated SendGrid IP addresses. 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. +IP pools can only be used with authenticated IP addresses. If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. @@ -2359,7 +2359,7 @@ If an IP pool is NOT specified for an email, it will use any IP available, inclu IP Pools allow you to group your dedicated SendGrid IP addresses. 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. +IP pools can only be used with authenticated IP addresses. If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. @@ -3504,7 +3504,7 @@ This endpoint allows you to approve an access attempt. *You may create up to 100 unique sender identities.* -Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. +Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### POST /senders @@ -3540,7 +3540,7 @@ Sender Identities are required to be verified before use. If your domain has bee **This endpoint allows you to retrieve a list of all sender identities that have been created for your account.** -Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. +Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### GET /senders @@ -3558,7 +3558,7 @@ Sender Identities are required to be verified before use. If your domain has bee **This endpoint allows you to retrieve a specific sender identity.** -Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. +Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### GET /senders/{sender_id} @@ -3576,7 +3576,7 @@ Sender Identities are required to be verified before use. If your domain has bee **This endpoint allows you to delete one of your sender identities.** -Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. +Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### DELETE /senders/{sender_id} @@ -3596,7 +3596,7 @@ Sender Identities are required to be verified before use. If your domain has bee **This endpoint allows you to update a sender identity.** -Updates to `from.email` require re-verification. If your domain has been whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. +Updates to `from.email` require re-verification. If your domain has been authenticated it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. Partial updates are allowed, but fields that are marked as "required" in the POST (create) endpoint must not be nil if that field is included in the PATCH request. @@ -3634,7 +3634,7 @@ Partial updates are allowed, but fields that are marked as "required" in the POS **This endpoint allows you to resend a sender identity verification email.** -Sender Identities are required to be verified before use. If your domain has been whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. +Sender Identities are required to be verified before use. If your domain has been authenticated it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### POST /senders/{sender_id}/resend_verification @@ -3650,2811 +3650,2812 @@ Sender Identities are required to be verified before use. If your domain has bee console.log(response.body); }) ``` - -# STATS - -## Retrieve global email statistics - -**This endpoint allows you to retrieve all of your global email statistics between a given date range.** - -Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their stats. + +# SENDER AUTHENTICATION -### GET /stats - - -```javascript - const queryParams = { - 'aggregated_by': 'day', - 'end_date': '2016-04-01', - 'limit': 1, - 'offset': 1, - 'start_date': '2016-01-01' -}; - request.qs = queryParams; - request.method = 'GET'; - request.url = '/v3/stats'; - client.request(request) - .then(([response, body]) => { - console.log(response.statusCode); - console.log(response.body); - }) -``` - -# SUBUSERS +## Create a domain authentication. -## Create Subuser +**This endpoint allows you to create an authentication for one of your domains.** -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. +If you are creating a domain authentication that you would like a subuser to use, you have two options: +1. Use the "username" parameter. This allows you to create an authenticated domain on behalf of your subuser. This means the subuser can see and modify the created authenticated domain. +2. Use the Association workflow (see Associate Domain section). This allows you to assign a domain authentication created by the parent to a subuser. This means the subuser will default to the assigned authenticated domain, but will not be able to see or modify that authentication. However, if the subuser creates their domain authentication it will overwrite the assigned domain authentication. -For more information about Subusers: +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -* [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) +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -### POST /subusers +### POST /whitelabel/domains ```javascript const data = { - "email": "John@example.com", + "automatic_security": false, + "custom_spf": true, + "default": true, + "domain": "example.com", "ips": [ - "1.1.1.1", - "2.2.2.2" + "192.168.1.1", + "192.168.1.2" ], - "password": "johns_password", - "username": "John@example.com" + "subdomain": "news", + "username": "john@example.com" }; request.body = data; request.method = 'POST'; - request.url = '/v3/subusers'; + request.url = '/v3/whitelabel/domains'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## List all Subusers +## List all domain authentications. -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 retrieve a list of all domain authentications you have created.** -For more information about Subusers: +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -* [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) +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -### GET /subusers +### GET /whitelabel/domains ```javascript const queryParams = { + 'domain': 'test_string', + 'exclude_subusers': 'true', 'limit': 1, 'offset': 1, 'username': 'test_string' }; request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/subusers'; - client.request(request) - .then(([response, body]) => { - console.log(response.statusCode); - console.log(response.body); - }) -``` -## Retrieve Subuser Reputations - -Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other adverse action happens on a sent email, it will affect your sender rating. - -This endpoint allows you to request the reputations for your subusers. - -### GET /subusers/reputations - - -```javascript - const queryParams = { - 'usernames': 'test_string' -}; - request.qs = queryParams; - request.method = 'GET'; - request.url = '/v3/subusers/reputations'; + request.url = '/v3/whitelabel/domains'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve email statistics for your subusers. +## Get the default domain authentication. -**This endpoint allows you to retrieve the email statistics for the given subusers.** +**This endpoint allows you to retrieve the default authentication for a domain.** -You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser. +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -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 on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| domain | string |The domain to find a default domain whitelabel for. | -### GET /subusers/stats +### GET /whitelabel/domains/default ```javascript - const queryParams = { - 'aggregated_by': 'day', - 'end_date': '2016-04-01', - 'limit': 1, - 'offset': 1, - 'start_date': '2016-01-01', - 'subusers': 'test_string' -}; - request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/subusers/stats'; + request.url = '/v3/whitelabel/domains/default'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve monthly stats for all subusers +## Disassociate a domain authentication from a given user. -**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** +**This endpoint allows you to disassociate a specific authentication from a 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. +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -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`. +Domain authentications can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's authenticated domains. To associate a domain authentication with a subuser, the parent account must first create the domain authentication and validate it. The parent may then associate the domain authentication via the subuser management tools. -For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -### GET /subusers/stats/monthly +## URI Parameters +| URI Parameter | Type | Required? | Description | +|---|---|---|---| +| username | string | required | Username for the subuser to find associated whitelabels for. | + +### DELETE /whitelabel/domains/subuser ```javascript - const queryParams = { - 'date': 'test_string', - 'limit': 1, - 'offset': 1, - 'sort_by_direction': 'asc', - 'sort_by_metric': 'test_string', - 'subuser': 'test_string' -}; - request.qs = queryParams; - request.method = 'GET'; - request.url = '/v3/subusers/stats/monthly'; + const data = None; + request.body = data; + request.method = 'DELETE'; + request.url = '/v3/whitelabel/domains/subuser'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve the totals for each email statistic metric for all subusers. +## List the domain authentications associated with the given user. -**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** +**This endpoint allows you to retrieve all of the domain authentications that have been assigned to a specific subuser.** +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -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. +Domain authentications can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's authenticated domains. To associate a domain authentication with a subuser, the parent account must first create the domain authentication and validate it. The parent may then associate the domain authentication via the subuser management tools. -For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -### GET /subusers/stats/sums +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| username | string | Username of the subuser to find associated whitelabels for. | + +### GET /whitelabel/domains/subuser ```javascript - const queryParams = { - 'aggregated_by': 'day', - 'end_date': '2016-04-01', - 'limit': 1, - 'offset': 1, - 'sort_by_direction': 'asc', - 'sort_by_metric': 'test_string', - 'start_date': '2016-01-01' -}; - request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/subusers/stats/sums'; + request.url = '/v3/whitelabel/domains/subuser'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a subuser +## Delete a domain authentication. -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 delete a domain authentication.** -For more information about Subusers: +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -* [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) +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -### DELETE /subusers/{subuser_name} +### DELETE /whitelabel/domains/{domain_id} ```javascript const data = None; request.body = data; request.method = 'DELETE'; - request.url = '/v3/subusers/{subuser_name}'; + request.url = '/v3/whitelabel/domains/{domain_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Enable/disable a subuser +## Update a domain authentication. -This endpoint allows you to enable or disable a subuser. +**This endpoint allows you to update the settings for a domain authentication.** -For more information about Subusers: +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -* [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) +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -### PATCH /subusers/{subuser_name} +### PATCH /whitelabel/domains/{domain_id} ```javascript const data = { - "disabled": false + "custom_spf": true, + "default": false }; request.body = data; request.method = 'PATCH'; - request.url = '/v3/subusers/{subuser_name}'; + request.url = '/v3/whitelabel/domains/{domain_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update IPs assigned to a subuser +## Retrieve a domain authentication. -Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. +**This endpoint allows you to retrieve a specific domain authentication.** -More information: +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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. -* [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) +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) -### PUT /subusers/{subuser_name}/ips +### GET /whitelabel/domains/{domain_id} ```javascript - const data = [ - "127.0.0.1" -]; - request.body = data; - request.method = 'PUT'; - request.url = '/v3/subusers/{subuser_name}/ips'; + request.method = 'GET'; + request.url = '/v3/whitelabel/domains/{domain_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update Monitor Settings for a subuser +## Associate a domain authentication with a given user. -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. +**This endpoint allows you to associate a specific domain authentication with a subuser.** -### PUT /subusers/{subuser_name}/monitor +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +Domain authentications can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's authenticated domains. To associate a domain authentication with a subuser, the parent account must first create the domain authentication and validate it. The parent may then associate the domain authentication via the subuser management tools. + +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| domain_id | integer | ID of the domain whitelabel to associate with the subuser. | + +### POST /whitelabel/domains/{domain_id}/subuser ```javascript const data = { - "email": "example@example.com", - "frequency": 500 + "username": "jane@example.com" }; request.body = data; - request.method = 'PUT'; - request.url = '/v3/subusers/{subuser_name}/monitor'; + request.method = 'POST'; + request.url = '/v3/whitelabel/domains/{domain_id}/subuser'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Create monitor settings +## Add an IP to a domain authentication. -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. +**This endpoint allows you to add an IP address to a domain authentication.** -### POST /subusers/{subuser_name}/monitor +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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 domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| id | integer | ID of the domain to which you are adding an IP | + +### POST /whitelabel/domains/{id}/ips ```javascript const data = { - "email": "example@example.com", - "frequency": 50000 + "ip": "192.168.0.1" }; request.body = data; request.method = 'POST'; - request.url = '/v3/subusers/{subuser_name}/monitor'; + request.url = '/v3/whitelabel/domains/{id}/ips'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete monitor settings +## Remove an IP from a domain authentication. -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. +**This endpoint allows you to remove a domain's IP address from that domain's authentication.** -### DELETE /subusers/{subuser_name}/monitor +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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 domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| id | integer | ID of the domain whitelabel to delete the IP from. | +| ip | string | IP to remove from the domain whitelabel. | + +### DELETE /whitelabel/domains/{id}/ips/{ip} ```javascript const data = None; request.body = data; request.method = 'DELETE'; - request.url = '/v3/subusers/{subuser_name}/monitor'; + request.url = '/v3/whitelabel/domains/{id}/ips/{ip}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve monitor settings for a subuser +## Validate a domain authentication. -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. +**This endpoint allows you to validate a domain authentication. If it fails, it will return an error message describing why the domain authentication could not be validated.** -### GET /subusers/{subuser_name}/monitor +A domain authentication allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Authenticating a domain allows you to replace sendgrid.net with your 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 domain authentication, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| id | integer |ID of the domain whitelabel to validate. | + +### POST /whitelabel/domains/{id}/validate ```javascript - request.method = 'GET'; - request.url = '/v3/subusers/{subuser_name}/monitor'; - client.request(request) - .then(([response, body]) => { - console.log(response.statusCode); - console.log(response.body); - }) -``` -## Retrieve the monthly email statistics for a single subuser - -**This endpoint allows you to retrieve the monthly email statistics for a specific subuser.** - -While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - -When using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics: -`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`. - -For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). - -### GET /subusers/{subuser_name}/stats/monthly - - -```javascript - const queryParams = { - 'date': 'test_string', - 'limit': 1, - 'offset': 1, - 'sort_by_direction': 'asc', - 'sort_by_metric': 'test_string' -}; - request.qs = queryParams; - request.method = 'GET'; - request.url = '/v3/subusers/{subuser_name}/stats/monthly'; + const data = None; + request.body = data; + request.method = 'POST'; + request.url = '/v3/whitelabel/domains/{id}/validate'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` - -# SUPPRESSION - -## Delete blocks - -**This endpoint allows you to delete all email addresses on your blocks list.** +## Create reverse DNS record -There are two options for deleting blocked emails: +**This endpoint allows you to create a reverse DNS record.** -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. +When creating a reverse DNS record, you should use the same subdomain that you used when you created a domain authentication. -[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 a filter flags the message content on the receiving server. +Reverse DNS consists of a subdomain and domain that will be used to generate a 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/User_Guide/Suppressions/blocks.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/). -### DELETE /suppression/blocks +### POST /whitelabel/ips ```javascript const data = { - "delete_all": false, - "emails": [ - "example1@example.com", - "example2@example.com" - ] + "domain": "example.com", + "ip": "192.168.1.1", + "subdomain": "email" }; request.body = data; - request.method = 'DELETE'; - request.url = '/v3/suppression/blocks'; + request.method = 'POST'; + request.url = '/v3/whitelabel/ips'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all blocks +## Retrieve all reverse DNS records -**This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.** +**This endpoint allows you to retrieve all of the reverse DNS records that have been created by this account.** -There are several causes for [blocked](https://sendgrid.com/docs/Glossary/blocks.html) emails: for example, your mail server IP address is on an ISP blacklist, or blocked by an ISP, or if the receiving server flags the message content. +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."). -For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). +Reverse DNS consists of a subdomain and domain that will be used to generate a 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. -### GET /suppression/blocks +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/). + +### GET /whitelabel/ips ```javascript const queryParams = { - 'end_time': 1, + 'ip': 'test_string', 'limit': 1, - 'offset': 1, - 'start_time': 1 + 'offset': 1 }; request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/suppression/blocks'; + request.url = '/v3/whitelabel/ips'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a specific block +## Delete an reverse DNS record -**This endpoint allows you to delete a specific email address from your blocks list.** +**This endpoint allows you to delete an reverse DNS record.** -[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 a filter flags the message content on the receiving server. +Reverse DNS consists of a subdomain and domain that will be used to generate a 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/User_Guide/Suppressions/blocks.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/). -### DELETE /suppression/blocks/{email} +### DELETE /whitelabel/ips/{id} ```javascript const data = None; request.body = data; request.method = 'DELETE'; - request.url = '/v3/suppression/blocks/{email}'; + request.url = '/v3/whitelabel/ips/{id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a specific block +## Retrieve an reverse DNS record -**This endpoint allows you to retrieve a specific email address from your blocks list.** +**This endpoint allows you to retrieve an reverse DNS record.** -[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 a filter flags the message content on the receiving server. +Reverse DNS consists of a subdomain and domain that will be used to generate a 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/User_Guide/Suppressions/blocks.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/). -### GET /suppression/blocks/{email} +### GET /whitelabel/ips/{id} ```javascript request.method = 'GET'; - request.url = '/v3/suppression/blocks/{email}'; + request.url = '/v3/whitelabel/ips/{id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete bounces - -**This endpoint allows you to delete all of your bounces. You can also use this endpoint to remove a specific email address from your bounce list.** - -A bounced email is when the message is undeliverable and then returned to the server that sent it. +## Validate an reverse DNS record -For more information see: +**This endpoint allows you to validate an reverse DNS record.** -* [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) +Reverse DNS consists of a subdomain and domain that will be used to generate a 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. -Note: the `delete_all` and `emails` parameters should be used independently of each other as they have different purposes. +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/). -### DELETE /suppression/bounces +### POST /whitelabel/ips/{id}/validate ```javascript - const data = { - "delete_all": true, - "emails": [ - "example@example.com", - "example2@example.com" - ] -}; + const data = None; request.body = data; - request.method = 'DELETE'; - request.url = '/v3/suppression/bounces'; + request.method = 'POST'; + request.url = '/v3/whitelabel/ips/{id}/validate'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all bounces - -**This endpoint allows you to retrieve all of your bounces.** +## Create a Branded Link -A bounced email is when the message is undeliverable and then returned to the server that sent it. +**This endpoint allows you to create a new link branding.** -For more information see: +Email link branding 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 > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information -* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/). -### GET /suppression/bounces +### POST /whitelabel/links ```javascript + const data = { + "default": true, + "domain": "example.com", + "subdomain": "mail" +}; + request.body = data; const queryParams = { - 'end_time': 1, - 'start_time': 1 + 'limit': 1, + 'offset': 1 }; request.qs = queryParams; - request.method = 'GET'; - request.url = '/v3/suppression/bounces'; + request.method = 'POST'; + request.url = '/v3/whitelabel/links'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a bounce - -**This endpoint allows you to remove an email address from your bounce list.** +## Retrieve all link brandings -A bounced email is when the message is undeliverable and then returned to the server that sent it. This endpoint allows you to delete a single email address from your bounce list. +**This endpoint allows you to retrieve all link brandings.** -For more information see: +Email link branding 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 > 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) +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/). -### DELETE /suppression/bounces/{email} +### GET /whitelabel/links ```javascript - const data = None; - request.body = data; const queryParams = { - 'email_address': 'example@example.com' + 'limit': 1 }; request.qs = queryParams; - request.method = 'DELETE'; - request.url = '/v3/suppression/bounces/{email}'; + request.method = 'GET'; + request.url = '/v3/whitelabel/links'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a Bounce +## Retrieve a Default Link Branding -**This endpoint allows you to retrieve a specific bounce for a given email address.** +**This endpoint allows you to retrieve the default link branding.** -A bounced email is when the message is undeliverable and then returned to the server that sent it. +Default link branding is the actual link branding to be used when sending messages. If there are multiple link brandings, the default is determined by the following order: + -For more information see: +Email link branding 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 > 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) +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/). -### GET /suppression/bounces/{email} +### GET /whitelabel/links/default ```javascript + const queryParams = { + 'domain': 'test_string' +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/suppression/bounces/{email}'; + request.url = '/v3/whitelabel/links/default'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete invalid emails - -**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 the 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 recipients' mail server. - -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. - -For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). - -### DELETE /suppression/invalid_emails +### DELETE /whitelabel/links/subuser ```javascript - const data = { - "delete_all": false, - "emails": [ - "example1@example.com", - "example2@example.com" - ] -}; + const data = None; request.body = data; + const queryParams = { + 'username': 'test_string' +}; + request.qs = queryParams; request.method = 'DELETE'; - request.url = '/v3/suppression/invalid_emails'; + request.url = '/v3/whitelabel/links/subuser'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all invalid emails +## Retrieve Associated Link Branding -**This endpoint allows you to retrieve a list of all invalid email addresses.** +**This endpoint allows you to retrieve the associated link branding for a subuser.** -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 recipients' mail server. +Link branding can be associated with subusers from the parent account. This functionality allows +subusers to send mail using their parent's link brands. To associate a link branding, the parent account +must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the Subuser Management page in the user interface. -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. +Email link branding 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/User_Guide/Suppressions/invalid_emails.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/). -### GET /suppression/invalid_emails +### GET /whitelabel/links/subuser ```javascript const queryParams = { - 'end_time': 1, - 'limit': 1, - 'offset': 1, - 'start_time': 1 + 'username': 'test_string' }; request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/suppression/invalid_emails'; + request.url = '/v3/whitelabel/links/subuser'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a specific invalid email +## Disassociate a Link Branding -**This endpoint allows you to remove a specific email address from the invalid email address list.** +**This endpoint allows you to disassociate a link branding from a subuser.** -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 recipients' mail server. +Link branding can be associated with subusers from the parent account. This functionality allows +subusers to send mail using their parent's link brands. To associate a link branding, the parent account +must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the Subuser Management page in the user interface. -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. +Email link branding 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/User_Guide/Suppressions/invalid_emails.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/). -### DELETE /suppression/invalid_emails/{email} +## Delete a Link Branding + +**This endpoint allows you to delete a link branding.** + +Email link branding 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/ui/account-and-settings/how-to-set-up-link-branding/). + +### DELETE /whitelabel/links/{id} ```javascript const data = None; request.body = data; request.method = 'DELETE'; - request.url = '/v3/suppression/invalid_emails/{email}'; + request.url = '/v3/whitelabel/links/{id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a specific invalid email - -**This endpoint allows you to retrieve a specific invalid email address.** +## Update a Link Branding -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 recipients' mail server. +**This endpoint allows you to update a specific link branding. You can use this endpoint to change a branded link's default status.** -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. +Email link branding 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/User_Guide/Suppressions/invalid_emails.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/). -### GET /suppression/invalid_emails/{email} +### PATCH /whitelabel/links/{id} ```javascript - request.method = 'GET'; - request.url = '/v3/suppression/invalid_emails/{email}'; + const data = { + "default": true +}; + request.body = data; + request.method = 'PATCH'; + request.url = '/v3/whitelabel/links/{id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete spam reports - -**This endpoint allows you to delete your spam reports.** +## Retrieve a Link Branding -There are two options for deleting spam reports: +**This endpoint allows you to retrieve a specific link branding.** -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. +Email link branding allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. -[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/ui/account-and-settings/how-to-set-up-link-branding/). -For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). +### GET /whitelabel/links/{id} -### DELETE /suppression/spam_reports + +```javascript + request.method = 'GET'; + request.url = '/v3/whitelabel/links/{id}'; + client.request(request) + .then(([response, body]) => { + console.log(response.statusCode); + console.log(response.body); + }) +``` +## Validate a Link Branding + +**This endpoint allows you to validate a link branding.** + +Email link branding 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/ui/account-and-settings/how-to-set-up-link-branding/). + +### POST /whitelabel/links/{id}/validate + + +```javascript + const data = None; + request.body = data; + request.method = 'POST'; + request.url = '/v3/whitelabel/links/{id}/validate'; + client.request(request) + .then(([response, body]) => { + console.log(response.statusCode); + console.log(response.body); + }) +``` +# Associate a Link Branding + +**This endpoint allows you to associate a link branding with a subuser account.** + +Link branding can be associated with subusers from the parent account. This functionality allows +subusers to send mail using their parent's link brands. To associate a link branding, the parent account +must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the Subuser Management page in the user interface. + +Email link branding 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/ui/account-and-settings/how-to-set-up-link-branding/). + +### POST /whitelabel/links/{link_id}/subuser ```javascript const data = { - "delete_all": false, - "emails": [ - "example1@example.com", - "example2@example.com" - ] + "username": "jane@example.com" }; request.body = data; - request.method = 'DELETE'; - request.url = '/v3/suppression/spam_reports'; + request.method = 'POST'; + request.url = '/v3/whitelabel/links/{link_id}/subuser'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all spam reports -**This endpoint allows you to retrieve all spam reports.** + +# STATS -[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. +## Retrieve global email statistics -For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). +**This endpoint allows you to retrieve all of your global email statistics between a given date range.** -### GET /suppression/spam_reports +Parent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their stats. + +### GET /stats ```javascript const queryParams = { - 'end_time': 1, + 'aggregated_by': 'day', + 'end_date': '2016-04-01', 'limit': 1, 'offset': 1, - 'start_time': 1 + 'start_date': '2016-01-01' }; request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/suppression/spam_reports'; + request.url = '/v3/stats'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a specific spam report + +# SUBUSERS -**This endpoint allows you to delete a specific spam report.** +## Create Subuser -[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 of your subusers. You can choose to retrieve specific subusers as well as limit the results that come back from the API. -For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). +For more information about Subusers: -### DELETE /suppression/spam_reports/{email} +* [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) + +### POST /subusers ```javascript - const data = None; + const data = { + "email": "John@example.com", + "ips": [ + "1.1.1.1", + "2.2.2.2" + ], + "password": "johns_password", + "username": "John@example.com" +}; request.body = data; - request.method = 'DELETE'; - request.url = '/v3/suppression/spam_reports/{email}'; + request.method = 'POST'; + request.url = '/v3/subusers'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a specific spam report +## List all Subusers -**This endpoint allows you to retrieve a specific spam report.** +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. -[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 about Subusers: -For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). +* [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) -### GET /suppression/spam_reports/{email} +### GET /subusers ```javascript + const queryParams = { + 'limit': 1, + 'offset': 1, + 'username': 'test_string' +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/suppression/spam_reports/{email}'; + request.url = '/v3/subusers'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all global suppressions +## Retrieve Subuser Reputations -**This endpoint allows you to retrieve a list of all email addresses that are globally suppressed.** +Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other adverse action happens on a sent email, it will affect your sender rating. -A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). +This endpoint allows you to request the reputations for your subusers. -### GET /suppression/unsubscribes +### GET /subusers/reputations ```javascript const queryParams = { - 'end_time': 1, - 'limit': 1, - 'offset': 1, - 'start_time': 1 + 'usernames': 'test_string' }; request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/suppression/unsubscribes'; + request.url = '/v3/subusers/reputations'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` - -# TEAMMATES +## Retrieve email statistics for your subusers. -## Invite teammate +**This endpoint allows you to retrieve the email statistics for the given subusers.** -This endpoint allows you to send a teammate invitation via email with a predefined set of scopes, or permissions. +You may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser. -**Note:** A teammate invite will expire after 7 days, but you may resend the invite at any time to reset the expiration date. +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. -Essentials, [Legacy Lite](https://sendgrid.com/docs/Classroom/Basics/Billing/legacy_lite_plan.html), and Free Trial users may create up to one teammate per account. There are no limits for how many teammates a Pro or higher account may create. +For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). -### POST /teammates +### GET /subusers/stats ```javascript - const data = { - "email": "teammate1@example.com", - "is_admin": false, - "scopes": [ - "user.profile.read", - "user.profile.update" - ] + const queryParams = { + 'aggregated_by': 'day', + 'end_date': '2016-04-01', + 'limit': 1, + 'offset': 1, + 'start_date': '2016-01-01', + 'subusers': 'test_string' }; - request.body = data; - request.method = 'POST'; - request.url = '/v3/teammates'; + request.qs = queryParams; + request.method = 'GET'; + request.url = '/v3/subusers/stats'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all teammates +## Retrieve monthly stats for all subusers -This endpoint allows you to retrieve a list of all current teammates. +**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.** -**Note:** The Response Header will include pagination info. For example: +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. -link: ```; rel="first"; title="1", ; rel="last"; title="2", ; rel="prev"; title="1"``` +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`. -### GET /teammates +For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + +### GET /subusers/stats/monthly ```javascript const queryParams = { + 'date': 'test_string', 'limit': 1, - 'offset': 1 + 'offset': 1, + 'sort_by_direction': 'asc', + 'sort_by_metric': 'test_string', + 'subuser': 'test_string' }; request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/teammates'; + request.url = '/v3/subusers/stats/monthly'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all pending teammates +## Retrieve the totals for each email statistic metric for all subusers. -This endpoint allows you to retrieve a list of all pending teammate invitations. +**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.** -**Note:** Each teammate invitation is valid for 7 days. Users may resend the invite to refresh the expiration date. -### GET /teammates/pending +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). + +### GET /subusers/stats/sums ```javascript + const queryParams = { + 'aggregated_by': 'day', + 'end_date': '2016-04-01', + 'limit': 1, + 'offset': 1, + 'sort_by_direction': 'asc', + 'sort_by_metric': 'test_string', + 'start_date': '2016-01-01' +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/teammates/pending'; + request.url = '/v3/subusers/stats/sums'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete pending teammate +## Delete a subuser -This endpoint allows you to delete a pending teammate invite. +This endpoint allows you to delete a subuser. This is a permanent action, once deleted a subuser cannot be retrieved. -### DELETE /teammates/pending/{token} +For more information about Subusers: + +* [User Guide > Subusers](https://sendgrid.com/docs/User_Guide/Settings/Subusers/index.html) +* [Classroom > How do I add more subusers to my account?](https://sendgrid.com/docs/Classroom/Basics/Account/how_do_i_add_more_subusers_to_my_account.html) + +### DELETE /subusers/{subuser_name} ```javascript const data = None; request.body = data; request.method = 'DELETE'; - request.url = '/v3/teammates/pending/{token}'; + request.url = '/v3/subusers/{subuser_name}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Resend teammate invite +## Enable/disable a subuser -This endpoint allows you to resend a teammate invite. +This endpoint allows you to enable or disable a subuser. -**Note:** Teammate invitations will expire after 7 days. Resending an invite will reset the expiration date. +For more information about Subusers: -### POST /teammates/pending/{token}/resend +* [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) + +### PATCH /subusers/{subuser_name} ```javascript - const data = None; + const data = { + "disabled": false +}; request.body = data; - request.method = 'POST'; - request.url = '/v3/teammates/pending/{token}/resend'; + request.method = 'PATCH'; + request.url = '/v3/subusers/{subuser_name}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete teammate +## Update IPs assigned to a subuser -This endpoint allows you to delete a teammate. +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. -**Only the parent user or an admin teammate can delete another teammate.** +More information: -### DELETE /teammates/{username} +* [How to request more IPs](https://sendgrid.com/docs/Classroom/Basics/Account/adding_an_additional_dedicated_ip_to_your_account.html) +* [How to setup reverse DNS](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/) + +### PUT /subusers/{subuser_name}/ips ```javascript - const data = None; + const data = [ + "127.0.0.1" +]; request.body = data; - request.method = 'DELETE'; - request.url = '/v3/teammates/{username}'; + request.method = 'PUT'; + request.url = '/v3/subusers/{subuser_name}/ips'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update teammate's permissions +## Update Monitor Settings for a subuser -This endpoint allows you to update a teammate's permissions. +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. -To turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have. - -**Only the parent user or other admin teammates can update another teammate's permissions.** - -**Admin users can only update permissions.** - -### PATCH /teammates/{username} +### PUT /subusers/{subuser_name}/monitor ```javascript const data = { - "is_admin": false, - "scopes": [ - "user.profile.read", - "user.profile.edit" - ] + "email": "example@example.com", + "frequency": 500 }; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/teammates/{username}'; + request.method = 'PUT'; + request.url = '/v3/subusers/{subuser_name}/monitor'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve specific teammate +## Create monitor settings -This endpoint allows you to retrieve a specific teammate by username. +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. -### GET /teammates/{username} +### POST /subusers/{subuser_name}/monitor ```javascript - request.method = 'GET'; - request.url = '/v3/teammates/{username}'; + const data = { + "email": "example@example.com", + "frequency": 50000 +}; + request.body = data; + request.method = 'POST'; + request.url = '/v3/subusers/{subuser_name}/monitor'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` - -# TEMPLATES - -## Create a transactional template. - -**This endpoint allows you to create 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. +## Delete monitor settings -Transactional templates are templates explicitly created 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). +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. -### POST /templates +### DELETE /subusers/{subuser_name}/monitor ```javascript - const data = { - "name": "example_name" -}; + const data = None; request.body = data; - request.method = 'POST'; - request.url = '/v3/templates'; + request.method = 'DELETE'; + request.url = '/v3/subusers/{subuser_name}/monitor'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all transactional templates. - -**This endpoint allows you to retrieve all transactional templates.** - -Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. +## Retrieve monitor settings for a subuser -Transactional templates are templates explicitly created 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). +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. -### GET /templates +### GET /subusers/{subuser_name}/monitor ```javascript request.method = 'GET'; - request.url = '/v3/templates'; + request.url = '/v3/subusers/{subuser_name}/monitor'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a template. +## Retrieve the monthly email statistics for a single subuser -**This endpoint allows you to delete a transactional template.** +**This endpoint allows you to retrieve the monthly email statistics for a specific subuser.** -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. +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. -Transactional templates are templates explicitly created 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). +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`. -### DELETE /templates/{template_id} +For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). + +### GET /subusers/{subuser_name}/stats/monthly ```javascript - const data = None; - request.body = data; - request.method = 'DELETE'; - request.url = '/v3/templates/{template_id}'; + const queryParams = { + 'date': 'test_string', + 'limit': 1, + 'offset': 1, + 'sort_by_direction': 'asc', + 'sort_by_metric': 'test_string' +}; + request.qs = queryParams; + request.method = 'GET'; + request.url = '/v3/subusers/{subuser_name}/stats/monthly'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Edit a transactional template. + +# SUPPRESSION -**This endpoint allows you to edit a transactional template.** +## Delete blocks -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. +**This endpoint allows you to delete all email addresses on your blocks list.** -Transactional templates are templates explicitly created 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). +There are two options for deleting blocked emails: -### PATCH /templates/{template_id} +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 a filter flags the message content on the receiving server. + +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). + +### DELETE /suppression/blocks ```javascript const data = { - "name": "new_example_name" + "delete_all": false, + "emails": [ + "example1@example.com", + "example2@example.com" + ] }; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/templates/{template_id}'; + request.method = 'DELETE'; + request.url = '/v3/suppression/blocks'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a single transactional template. +## Retrieve all blocks -**This endpoint allows you to retrieve a single transactional template.** +**This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list.** -Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. +There are several causes for [blocked](https://sendgrid.com/docs/Glossary/blocks.html) emails: for example, your mail server IP address is on an ISP blacklist, or blocked by an ISP, or if the receiving server flags the message content. -Transactional templates are templates explicitly created 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). +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). -### GET /templates/{template_id} +### GET /suppression/blocks ```javascript + const queryParams = { + 'end_time': 1, + 'limit': 1, + 'offset': 1, + 'start_time': 1 +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/templates/{template_id}'; + request.url = '/v3/suppression/blocks'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Create a new transactional template version. +## Delete a specific block -**This endpoint allows you to create a new version of a template.** +**This endpoint allows you to delete a specific email address from your blocks list.** -Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. +[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 a filter flags the message content on the receiving server. -For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). -### POST /templates/{template_id}/versions +### DELETE /suppression/blocks/{email} ```javascript - const data = { - "active": 1, - "html_content": "<%body%>", - "name": "example_version_name", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543" -}; + const data = None; request.body = data; - request.method = 'POST'; - request.url = '/v3/templates/{template_id}/versions'; + request.method = 'DELETE'; + request.url = '/v3/suppression/blocks/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a transactional template version. - -**This endpoint allows you to delete one of your transactional template versions.** +## Retrieve a specific block -Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. +**This endpoint allows you to retrieve a specific email address from your blocks list.** -For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.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 a filter flags the message content on the receiving server. -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| template_id | string | The ID of the original template | -| version_id | string | The ID of the template version | +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). -### DELETE /templates/{template_id}/versions/{version_id} +### GET /suppression/blocks/{email} ```javascript - const data = None; - request.body = data; - request.method = 'DELETE'; - request.url = '/v3/templates/{template_id}/versions/{version_id}'; + request.method = 'GET'; + request.url = '/v3/suppression/blocks/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Edit a transactional template version. +## Delete bounces -**This endpoint allows you to edit a version of one of your transactional templates.** +**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.** -Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. +A bounced email is when the message is undeliverable and then returned to the server that sent it. -For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). +For more information see: -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| template_id | string | The ID of the original template | -| version_id | string | The ID of the template version | +* [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) -### PATCH /templates/{template_id}/versions/{version_id} +Note: the `delete_all` and `emails` parameters should be used independently of each other as they have different purposes. + +### DELETE /suppression/bounces ```javascript const data = { - "active": 1, - "html_content": "<%body%>", - "name": "updated_example_name", - "plain_content": "<%body%>", - "subject": "<%subject%>" + "delete_all": true, + "emails": [ + "example@example.com", + "example2@example.com" + ] }; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/templates/{template_id}/versions/{version_id}'; + request.method = 'DELETE'; + request.url = '/v3/suppression/bounces'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a specific transactional template version. +## Retrieve all bounces -**This endpoint allows you to retrieve a specific version of a template.** +**This endpoint allows you to retrieve all of your bounces.** -Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. +A bounced email is when the message is undeliverable and then returned to the server that sent it. -For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). +For more information see: -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| template_id | string | The ID of the original template | -| version_id | string | The ID of the template version | +* [User Guide > Bounces](https://sendgrid.com/docs/User_Guide/Suppressions/bounces.html) for more information +* [Glossary > Bounces](https://sendgrid.com/docs/Glossary/Bounces.html) -### GET /templates/{template_id}/versions/{version_id} +### GET /suppression/bounces ```javascript + const queryParams = { + 'end_time': 1, + 'start_time': 1 +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/templates/{template_id}/versions/{version_id}'; + request.url = '/v3/suppression/bounces'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Activate a transactional template version. - -**This endpoint allows you to activate a version of one of your templates.** +## Delete a bounce -Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. +**This endpoint allows you to remove an email address from your bounce list.** +A bounced email is when the message is undeliverable and then returned to the server that sent it. This endpoint allows you to delete a single email address from your bounce list. -For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). +For more information see: -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| template_id | string | The ID of the original template | -| version_id | string | The ID of the template version | +* [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) -### POST /templates/{template_id}/versions/{version_id}/activate +### DELETE /suppression/bounces/{email} ```javascript const data = None; request.body = data; - request.method = 'POST'; - request.url = '/v3/templates/{template_id}/versions/{version_id}/activate'; + const queryParams = { + 'email_address': 'example@example.com' +}; + request.qs = queryParams; + request.method = 'DELETE'; + request.url = '/v3/suppression/bounces/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` - -# TRACKING SETTINGS +## Retrieve a Bounce -## Retrieve Tracking Settings +**This endpoint allows you to retrieve a specific bounce for a given email address.** -**This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** +A bounced email is when the message is undeliverable and then returned to the server that sent it. -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 see: -For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). +* [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) -### GET /tracking_settings +### GET /suppression/bounces/{email} ```javascript - const queryParams = { - 'limit': 1, - 'offset': 1 -}; - request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/tracking_settings'; + request.url = '/v3/suppression/bounces/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update Click Tracking Settings +## Delete invalid emails -**This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** +**This endpoint allows you to remove email addresses from your invalid email address list.** -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. +There are two options for deleting invalid email addresses: -For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). +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 the addresses in an array in the request body. -### PATCH /tracking_settings/click +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 recipients' mail server. + +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. + +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + +### DELETE /suppression/invalid_emails ```javascript const data = { - "enabled": true + "delete_all": false, + "emails": [ + "example1@example.com", + "example2@example.com" + ] }; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/tracking_settings/click'; + request.method = 'DELETE'; + request.url = '/v3/suppression/invalid_emails'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve Click Track Settings +## Retrieve all invalid emails -**This endpoint allows you to retrieve your current click tracking setting.** +**This endpoint allows you to retrieve a list of all invalid email addresses.** -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. +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 recipients' mail server. -For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. -### GET /tracking_settings/click +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). + +### GET /suppression/invalid_emails ```javascript + const queryParams = { + 'end_time': 1, + 'limit': 1, + 'offset': 1, + 'start_time': 1 +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/tracking_settings/click'; + request.url = '/v3/suppression/invalid_emails'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update Google Analytics Settings - -**This endpoint allows you to update your current setting for Google Analytics.** +## Delete a specific invalid email -For more information about using Google Analytics, please refer to [Googles 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). +**This endpoint allows you to remove a specific email address from the invalid email address list.** -We default the settings to Googles 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). +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 recipients' mail 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. +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. -For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). -### PATCH /tracking_settings/google_analytics +### DELETE /suppression/invalid_emails/{email} ```javascript - const data = { - "enabled": true, - "utm_campaign": "website", - "utm_content": "", - "utm_medium": "email", - "utm_source": "sendgrid.com", - "utm_term": "" -}; + const data = None; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/tracking_settings/google_analytics'; + request.method = 'DELETE'; + request.url = '/v3/suppression/invalid_emails/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve Google Analytics Settings - -**This endpoint allows you to retrieve your current setting for Google Analytics.** +## Retrieve a specific invalid email -For more information about using Google Analytics, please refer to [Googles 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). +**This endpoint allows you to retrieve a specific invalid email address.** -We default the settings to Googles 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). +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 recipients' mail 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. +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our server or the recipient mail server. -For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/invalid_emails.html). -### GET /tracking_settings/google_analytics +### GET /suppression/invalid_emails/{email} ```javascript request.method = 'GET'; - request.url = '/v3/tracking_settings/google_analytics'; + request.url = '/v3/suppression/invalid_emails/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update Open Tracking Settings +## Delete spam reports -**This endpoint allows you to update your current settings for open tracking.** +**This endpoint allows you to delete your spam reports.** -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 SendGrids 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 reported by the Event Webhook. +There are two options for deleting spam reports: -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. +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 about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.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. -### PATCH /tracking_settings/open +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). + +### DELETE /suppression/spam_reports ```javascript const data = { - "enabled": true + "delete_all": false, + "emails": [ + "example1@example.com", + "example2@example.com" + ] }; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/tracking_settings/open'; - client.request(request) - .then(([response, body]) => { - console.log(response.statusCode); - console.log(response.body); - }) -``` -## Get Open Tracking Settings - -**This endpoint allows you to retrieve your current settings for open tracking.** - -Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids 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 reported by the Event Webhook. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). - -### GET /tracking_settings/open - - -```javascript - request.method = 'GET'; - request.url = '/v3/tracking_settings/open'; + request.method = 'DELETE'; + request.url = '/v3/suppression/spam_reports'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update Subscription Tracking Settings - -**This endpoint allows you to update your current settings for subscription tracking.** +## Retrieve all spam reports -Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. +**This endpoint allows you to retrieve all spam reports.** -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. +[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 about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). -### PATCH /tracking_settings/subscription +### GET /suppression/spam_reports ```javascript - const data = { - "enabled": true, - "html_content": "html content", - "landing": "landing page html", - "plain_content": "text content", - "replace": "replacement tag", - "url": "url" + const queryParams = { + 'end_time': 1, + 'limit': 1, + 'offset': 1, + 'start_time': 1 }; - request.body = data; - request.method = 'PATCH'; - request.url = '/v3/tracking_settings/subscription'; + request.qs = queryParams; + request.method = 'GET'; + request.url = '/v3/suppression/spam_reports'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve Subscription Tracking Settings - -**This endpoint allows you to retrieve your current settings for subscription tracking.** +## Delete a specific spam report -Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. +**This endpoint allows you to delete a specific spam report.** -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. +[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 about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). -### GET /tracking_settings/subscription +### DELETE /suppression/spam_reports/{email} ```javascript - request.method = 'GET'; - request.url = '/v3/tracking_settings/subscription'; + const data = None; + request.body = data; + request.method = 'DELETE'; + request.url = '/v3/suppression/spam_reports/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` - -# USER - -## Get a user's account information. - -**This endpoint allows you to retrieve your user account details.** - -Your user's account information includes the user's account type and reputation. +## Retrieve a specific spam report -Keeping your user profile up to date is essential. 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) +For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/spam_reports.html). -### GET /user/account +### GET /suppression/spam_reports/{email} ```javascript request.method = 'GET'; - request.url = '/v3/user/account'; + request.url = '/v3/suppression/spam_reports/{email}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve your credit balance +## Retrieve all global suppressions -**This endpoint allows you to retrieve the current credit balance for your account.** +**This endpoint allows you to retrieve a list of all email addresses that are globally suppressed.** -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 [Classroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html). +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). -### GET /user/credits +### GET /suppression/unsubscribes ```javascript + const queryParams = { + 'end_time': 1, + 'limit': 1, + 'offset': 1, + 'start_time': 1 +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/user/credits'; + request.url = '/v3/suppression/unsubscribes'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update your account email address + +# TEAMMATES -**This endpoint allows you to update the email address currently on file for your account.** +## Invite teammate -Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. +This endpoint allows you to send a teammate invitation via email with a predefined set of scopes, or permissions. -For more information about your user profile: +**Note:** A teammate invite will expire after 7 days, but you may resend the invite at any time to reset the expiration date. -* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) +Essentials, [Legacy Lite](https://sendgrid.com/docs/Classroom/Basics/Billing/legacy_lite_plan.html), and Free Trial users may create up to one teammate per account. There are no limits for how many teammates a Pro or higher account may create. -### PUT /user/email +### POST /teammates ```javascript const data = { - "email": "example@example.com" + "email": "teammate1@example.com", + "is_admin": false, + "scopes": [ + "user.profile.read", + "user.profile.update" + ] }; request.body = data; - request.method = 'PUT'; - request.url = '/v3/user/email'; + request.method = 'POST'; + request.url = '/v3/teammates'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve your account email address - -**This endpoint allows you to retrieve the email address currently on file for your account.** +## Retrieve all teammates -Keeping your user profile up to date is essential. 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 list of all current teammates. -For more information about your user profile: +**Note:** The Response Header will include pagination info. For example: -* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) +link: ```; rel="first"; title="1", ; rel="last"; title="2", ; rel="prev"; title="1"``` -### GET /user/email +### GET /teammates ```javascript + const queryParams = { + 'limit': 1, + 'offset': 1 +}; + request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/user/email'; + request.url = '/v3/teammates'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update your password - -**This endpoint allows you to update your password.** - -Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. +## Retrieve all pending teammates -For more information about your user profile: +This endpoint allows you to retrieve a list of all pending teammate invitations. -* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) +**Note:** Each teammate invitation is valid for 7 days. Users may resend the invite to refresh the expiration date. -### PUT /user/password +### GET /teammates/pending ```javascript - const data = { - "new_password": "new_password", - "old_password": "old_password" -}; - request.body = data; - request.method = 'PUT'; - request.url = '/v3/user/password'; + request.method = 'GET'; + request.url = '/v3/teammates/pending'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update a user's profile +## Delete pending teammate -**This endpoint allows you to update your current profile details.** +This endpoint allows you to delete a pending teammate invite. -Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. +### DELETE /teammates/pending/{token} -For more information about your user profile: -* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) +```javascript + const data = None; + request.body = data; + request.method = 'DELETE'; + request.url = '/v3/teammates/pending/{token}'; + client.request(request) + .then(([response, body]) => { + console.log(response.statusCode); + console.log(response.body); + }) +``` +## Resend teammate invite -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. +This endpoint allows you to resend a teammate invite. -### PATCH /user/profile +**Note:** Teammate invitations will expire after 7 days. Resending an invite will reset the expiration date. + +### POST /teammates/pending/{token}/resend ```javascript - const data = { - "city": "Orange", - "first_name": "Example", - "last_name": "User" -}; + const data = None; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/user/profile'; + request.method = 'POST'; + request.url = '/v3/teammates/pending/{token}/resend'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Get a user's profile - -Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. +## Delete teammate -For more information about your user profile: +This endpoint allows you to delete a teammate. -* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) +**Only the parent user or an admin teammate can delete another teammate.** -### GET /user/profile +### DELETE /teammates/{username} ```javascript - request.method = 'GET'; - request.url = '/v3/user/profile'; + const data = None; + request.body = data; + request.method = 'DELETE'; + request.url = '/v3/teammates/{username}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Cancel or pause a scheduled send +## Update teammate's permissions -**This endpoint allows you to cancel or pause an email that has been scheduled to be sent.** +This endpoint allows you to update a teammate's permissions. -If the maximum number of cancellations/pauses are added, HTTP 400 will -be returned. +To turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have. -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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. +**Only the parent user or other admin teammates can update another teammate's permissions.** -### POST /user/scheduled_sends +**Admin users can only update permissions.** + +### PATCH /teammates/{username} ```javascript const data = { - "batch_id": "YOUR_BATCH_ID", - "status": "pause" + "is_admin": false, + "scopes": [ + "user.profile.read", + "user.profile.edit" + ] }; request.body = data; - request.method = 'POST'; - request.url = '/v3/user/scheduled_sends'; + request.method = 'PATCH'; + request.url = '/v3/teammates/{username}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all scheduled sends - -**This endpoint allows you to retrieve all cancel/paused scheduled send information.** +## Retrieve specific teammate -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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. +This endpoint allows you to retrieve a specific teammate by username. -### GET /user/scheduled_sends +### GET /teammates/{username} ```javascript request.method = 'GET'; - request.url = '/v3/user/scheduled_sends'; + request.url = '/v3/teammates/{username}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a cancellation or pause of a scheduled send + +# TEMPLATES -**This endpoint allows you to delete the cancellation/pause of a scheduled send.** +## Create a transactional template. -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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. +**This endpoint allows you to create a transactional template.** -### DELETE /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 explicitly created 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). + +### POST /templates ```javascript - const data = None; + const data = { + "name": "example_name" +}; request.body = data; - request.method = 'DELETE'; - request.url = '/v3/user/scheduled_sends/{batch_id}'; + request.method = 'POST'; + request.url = '/v3/templates'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update user scheduled send information +## Retrieve all transactional templates. -**This endpoint allows you to update the status of a scheduled send for the given `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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. +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. -### PATCH /user/scheduled_sends/{batch_id} +Transactional templates are templates explicitly created 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). + +### GET /templates ```javascript - const data = { - "status": "pause" -}; - request.body = data; - request.method = 'PATCH'; - request.url = '/v3/user/scheduled_sends/{batch_id}'; + request.method = 'GET'; + request.url = '/v3/templates'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve scheduled send +## Delete a template. -**This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.** +**This endpoint allows you to delete a transactional template.** -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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. +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. -### GET /user/scheduled_sends/{batch_id} +Transactional templates are templates explicitly created 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). + +### DELETE /templates/{template_id} ```javascript - request.method = 'GET'; - request.url = '/v3/user/scheduled_sends/{batch_id}'; + const data = None; + request.body = data; + request.method = 'DELETE'; + request.url = '/v3/templates/{template_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update Enforced TLS settings +## Edit a transactional template. -**This endpoint allows you to update your current Enforced TLS settings.** +**This endpoint allows you to edit a transactional template.** -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. +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. -**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. +Transactional templates are templates explicitly created 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). -### PATCH /user/settings/enforced_tls +### PATCH /templates/{template_id} ```javascript const data = { - "require_tls": true, - "require_valid_cert": false + "name": "new_example_name" }; request.body = data; request.method = 'PATCH'; - request.url = '/v3/user/settings/enforced_tls'; + request.url = '/v3/templates/{template_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve current Enforced TLS settings. +## Retrieve a single transactional template. -**This endpoint allows you to retrieve your current Enforced TLS settings.** +**This endpoint allows you to retrieve a single transactional template.** -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. +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. -**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. +Transactional templates are templates explicitly created 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). -### GET /user/settings/enforced_tls +### GET /templates/{template_id} ```javascript request.method = 'GET'; - request.url = '/v3/user/settings/enforced_tls'; + request.url = '/v3/templates/{template_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update your username - -**This endpoint allows you to update the username for your account.** +## Create a new transactional template version. -Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. +**This endpoint allows you to create a new version of a template.** -For more information about your user profile: +Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. -* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) +For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). -### PUT /user/username +### POST /templates/{template_id}/versions ```javascript const data = { - "username": "test_username" + "active": 1, + "html_content": "<%body%>", + "name": "example_version_name", + "plain_content": "<%body%>", + "subject": "<%subject%>", + "template_id": "ddb96bbc-9b92-425e-8979-99464621b543" }; request.body = data; - request.method = 'PUT'; - request.url = '/v3/user/username'; + request.method = 'POST'; + request.url = '/v3/templates/{template_id}/versions'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve your username +## Delete a transactional template version. -**This endpoint allows you to retrieve your current account username.** +**This endpoint allows you to delete one of your transactional template versions.** -Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. +Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. -For more information about your user profile: +For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). -* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| template_id | string | The ID of the original template | +| version_id | string | The ID of the template version | -### GET /user/username +### DELETE /templates/{template_id}/versions/{version_id} ```javascript - request.method = 'GET'; - request.url = '/v3/user/username'; + const data = None; + request.body = data; + request.method = 'DELETE'; + request.url = '/v3/templates/{template_id}/versions/{version_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update Event Notification Settings +## Edit a transactional template version. -**This endpoint allows you to update your current event webhook settings.** +**This endpoint allows you to edit a version of one of your transactional templates.** -If an event type is marked as `true`, then the event webhook will include information about that event. +Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. -SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. +For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). -Typical 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. +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| template_id | string | The ID of the original template | +| version_id | string | The ID of the template version | -### PATCH /user/webhooks/event/settings +### PATCH /templates/{template_id}/versions/{version_id} ```javascript const data = { - "bounce": true, - "click": true, - "deferred": true, - "delivered": true, - "dropped": true, - "enabled": true, - "group_resubscribe": true, - "group_unsubscribe": true, - "open": true, - "processed": true, - "spam_report": true, - "unsubscribe": true, - "url": "url" + "active": 1, + "html_content": "<%body%>", + "name": "updated_example_name", + "plain_content": "<%body%>", + "subject": "<%subject%>" }; request.body = data; request.method = 'PATCH'; - request.url = '/v3/user/webhooks/event/settings'; + request.url = '/v3/templates/{template_id}/versions/{version_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve Event Webhook settings +## Retrieve a specific transactional template version. -**This endpoint allows you to retrieve your current event webhook settings.** +**This endpoint allows you to retrieve a specific version of a template.** -If an event type is marked as `true`, then the event webhook will include information about that event. +Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. -SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. +For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). -Typical 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. +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| template_id | string | The ID of the original template | +| version_id | string | The ID of the template version | -### GET /user/webhooks/event/settings +### GET /templates/{template_id}/versions/{version_id} ```javascript request.method = 'GET'; - request.url = '/v3/user/webhooks/event/settings'; + request.url = '/v3/templates/{template_id}/versions/{version_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Test Event Notification Settings +## Activate a transactional template version. -**This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** +**This endpoint allows you to activate a version of one of your templates.** -SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. +Each transactional template can have multiple versions, each version with unique subject and content. Each user can have up to 300 versions across all templates. -Typical 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. -### POST /user/webhooks/event/test +For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| template_id | string | The ID of the original template | +| version_id | string | The ID of the template version | + +### POST /templates/{template_id}/versions/{version_id}/activate ```javascript - const data = { - "url": "url" -}; + const data = None; request.body = data; request.method = 'POST'; - request.url = '/v3/user/webhooks/event/test'; + request.url = '/v3/templates/{template_id}/versions/{version_id}/activate'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Create a parse setting + +# TRACKING SETTINGS -**This endpoint allows you to create a new inbound parse setting.** +## Retrieve Tracking Settings -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). +**This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account.** -### POST /user/webhooks/parse/settings +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). + +### GET /tracking_settings ```javascript - const data = { - "hostname": "myhostname.com", - "send_raw": false, - "spam_check": true, - "url": "http://email.myhosthame.com" + const queryParams = { + 'limit': 1, + 'offset': 1 }; - request.body = data; - request.method = 'POST'; - request.url = '/v3/user/webhooks/parse/settings'; + request.qs = queryParams; + request.method = 'GET'; + request.url = '/v3/tracking_settings'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all parse settings +## Update Click Tracking Settings -**This endpoint allows you to retrieve all of your current inbound parse settings.** +**This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint.** -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). +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. -### GET /user/webhooks/parse/settings +For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + +### PATCH /tracking_settings/click ```javascript - request.method = 'GET'; - request.url = '/v3/user/webhooks/parse/settings'; + const data = { + "enabled": true +}; + request.body = data; + request.method = 'PATCH'; + request.url = '/v3/tracking_settings/click'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a parse setting +## Retrieve Click Track Settings -**This endpoint allows you to delete a specific inbound parse setting.** +**This endpoint allows you to retrieve your current click tracking setting.** -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). +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. -### DELETE /user/webhooks/parse/settings/{hostname} +For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + +### GET /tracking_settings/click ```javascript - const data = None; - request.body = data; - request.method = 'DELETE'; - request.url = '/v3/user/webhooks/parse/settings/{hostname}'; + request.method = 'GET'; + request.url = '/v3/tracking_settings/click'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update a parse setting +## Update Google Analytics Settings -**This endpoint allows you to update a specific inbound parse setting.** +**This endpoint allows you to update your current setting for Google Analytics.** -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). +For more information about using Google Analytics, please refer to [Googles 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). -### PATCH /user/webhooks/parse/settings/{hostname} +We default the settings to Googles 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). + +### PATCH /tracking_settings/google_analytics ```javascript const data = { - "send_raw": true, - "spam_check": false, - "url": "http://newdomain.com/parse" + "enabled": true, + "utm_campaign": "website", + "utm_content": "", + "utm_medium": "email", + "utm_source": "sendgrid.com", + "utm_term": "" }; request.body = data; request.method = 'PATCH'; - request.url = '/v3/user/webhooks/parse/settings/{hostname}'; + request.url = '/v3/tracking_settings/google_analytics'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a specific parse setting +## Retrieve Google Analytics Settings + +**This endpoint allows you to retrieve your current setting for Google Analytics.** + +For more information about using Google Analytics, please refer to [Googles 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 Googles 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). + +### GET /tracking_settings/google_analytics + + +```javascript + request.method = 'GET'; + request.url = '/v3/tracking_settings/google_analytics'; + client.request(request) + .then(([response, body]) => { + console.log(response.statusCode); + console.log(response.body); + }) +``` +## Update Open Tracking Settings + +**This endpoint allows you to update your current settings for open tracking.** + +Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids 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 reported by the Event Webhook. -**This endpoint allows you to retrieve a specific inbound parse setting.** +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). +For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). -### GET /user/webhooks/parse/settings/{hostname} +### PATCH /tracking_settings/open ```javascript - request.method = 'GET'; - request.url = '/v3/user/webhooks/parse/settings/{hostname}'; + const data = { + "enabled": true +}; + request.body = data; + request.method = 'PATCH'; + request.url = '/v3/tracking_settings/open'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieves Inbound Parse Webhook statistics. +## Get Open Tracking Settings -**This endpoint allows you to retrieve the statistics for your Parse Webhook usage.** +**This endpoint allows you to retrieve your current settings for open tracking.** -SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incoming 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. +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 SendGrids 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 reported by the Event Webhook. -There are many 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). +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. -### GET /user/webhooks/parse/stats +For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). + +### GET /tracking_settings/open ```javascript - const queryParams = { - 'aggregated_by': 'day', - 'end_date': '2016-04-01', - 'limit': 'test_string', - 'offset': 'test_string', - 'start_date': '2016-01-01' -}; - request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/user/webhooks/parse/stats'; + request.url = '/v3/tracking_settings/open'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` - -# WHITELABEL - -## Create a domain whitelabel. +## Update Subscription Tracking Settings -**This endpoint allows you to create a whitelabel for one of your domains.** +**This endpoint allows you to update your current settings for subscription tracking.** -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 can 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 whitelabel it will overwrite the assigned whitelabel. +Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe 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 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. +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 on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). -### POST /whitelabel/domains +### PATCH /tracking_settings/subscription ```javascript const data = { - "automatic_security": false, - "custom_spf": true, - "default": true, - "domain": "example.com", - "ips": [ - "192.168.1.1", - "192.168.1.2" - ], - "subdomain": "news", - "username": "john@example.com" + "enabled": true, + "html_content": "html content", + "landing": "landing page html", + "plain_content": "text content", + "replace": "replacement tag", + "url": "url" }; request.body = data; - request.method = 'POST'; - request.url = '/v3/whitelabel/domains'; + request.method = 'PATCH'; + request.url = '/v3/tracking_settings/subscription'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## List all domain whitelabels. +## Retrieve Subscription Tracking Settings + +**This endpoint allows you to retrieve your current settings for subscription tracking.** -**This endpoint allows you to retrieve a list of all domain whitelabels you have created.** +Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe 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 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. +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 on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +For more information about tracking, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/tracking.html). -### GET /whitelabel/domains +### GET /tracking_settings/subscription ```javascript - const queryParams = { - 'domain': 'test_string', - 'exclude_subusers': 'true', - 'limit': 1, - 'offset': 1, - 'username': 'test_string' -}; - request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/whitelabel/domains'; + request.url = '/v3/tracking_settings/subscription'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Get the default domain whitelabel. + +# USER -**This endpoint allows you to retrieve the default whitelabel for a domain.** +## Get a user's account information. -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 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 your user account details.** -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +Your user's account information includes the user's account type and reputation. -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| domain | string |The domain to find a default domain whitelabel for. | +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -### GET /whitelabel/domains/default +For more information about your user profile: + +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + +### GET /user/account ```javascript request.method = 'GET'; - request.url = '/v3/whitelabel/domains/default'; + request.url = '/v3/user/account'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Disassociate a domain whitelabel from a given user. - -**This endpoint allows you to disassociate a specific whitelabel from a subuser.** - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. +## Retrieve your credit balance -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +**This endpoint allows you to retrieve the current credit balance for your account.** -## URI Parameters -| URI Parameter | Type | Required? | Description | -|---|---|---|---| -| username | string | required | Username for the subuser to find associated whitelabels for. | +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 [Classroom](https://sendgrid.com/docs/Classroom/Basics/Billing/billing_info_and_faqs.html). -### DELETE /whitelabel/domains/subuser +### GET /user/credits ```javascript - const data = None; - request.body = data; - request.method = 'DELETE'; - request.url = '/v3/whitelabel/domains/subuser'; + request.method = 'GET'; + request.url = '/v3/user/credits'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## List the domain whitelabel associated with the given user. - -**This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser.** +## Update your account email address -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 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 update the email address currently on file for your account.** -Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +For more information about your user profile: -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| username | string | Username of the subuser to find associated whitelabels for. | +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) -### GET /whitelabel/domains/subuser +### PUT /user/email ```javascript - request.method = 'GET'; - request.url = '/v3/whitelabel/domains/subuser'; + const data = { + "email": "example@example.com" +}; + request.body = data; + request.method = 'PUT'; + request.url = '/v3/user/email'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a domain whitelabel. +## Retrieve your account email address -**This endpoint allows you to delete a domain whitelabel.** +**This endpoint allows you to retrieve the email address currently on file for your account.** -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 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. +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +For more information about your user profile: -### DELETE /whitelabel/domains/{domain_id} +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) + +### GET /user/email ```javascript - const data = None; - request.body = data; - request.method = 'DELETE'; - request.url = '/v3/whitelabel/domains/{domain_id}'; + request.method = 'GET'; + request.url = '/v3/user/email'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update a domain whitelabel. +## Update your password + +**This endpoint allows you to update your password.** -**This endpoint allows you to update the settings for a domain whitelabel.** +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -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 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 your user profile: -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) -### PATCH /whitelabel/domains/{domain_id} +### PUT /user/password ```javascript const data = { - "custom_spf": true, - "default": false + "new_password": "new_password", + "old_password": "old_password" }; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/whitelabel/domains/{domain_id}'; + request.method = 'PUT'; + request.url = '/v3/user/password'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a domain whitelabel. +## Update a user's profile + +**This endpoint allows you to update your current profile details.** -**This endpoint allows you to retrieve a specific domain whitelabel.** +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -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 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 your user profile: -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) -### GET /whitelabel/domains/{domain_id} +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. + +### PATCH /user/profile ```javascript - request.method = 'GET'; - request.url = '/v3/whitelabel/domains/{domain_id}'; + const data = { + "city": "Orange", + "first_name": "Example", + "last_name": "User" +}; + request.body = data; + request.method = 'PATCH'; + request.url = '/v3/user/profile'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Associate a domain whitelabel with a given user. - -**This endpoint allows you to associate a specific domain whitelabel with a subuser.** - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your 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. +## Get a user's profile -Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +For more information about your user profile: -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| domain_id | integer | ID of the domain whitelabel to associate with the subuser. | +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) -### POST /whitelabel/domains/{domain_id}/subuser +### GET /user/profile ```javascript - const data = { - "username": "jane@example.com" -}; - request.body = data; - request.method = 'POST'; - request.url = '/v3/whitelabel/domains/{domain_id}/subuser'; + request.method = 'GET'; + request.url = '/v3/user/profile'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Add an IP to a domain whitelabel. - -**This endpoint allows you to add an IP address to a domain whitelabel.** +## Cancel or pause a scheduled send -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 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 cancel or pause an email that has been scheduled to be sent.** -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +If the maximum number of cancellations/pauses are added, HTTP 400 will +be returned. -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| id | integer | ID of the domain to which you are adding an IP | +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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. -### POST /whitelabel/domains/{id}/ips +### POST /user/scheduled_sends ```javascript const data = { - "ip": "192.168.0.1" + "batch_id": "YOUR_BATCH_ID", + "status": "pause" }; request.body = data; request.method = 'POST'; - request.url = '/v3/whitelabel/domains/{id}/ips'; + request.url = '/v3/user/scheduled_sends'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Remove an IP from a domain whitelabel. - -**This endpoint allows you to remove a domain's IP address from that domain's whitelabel.** - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your 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. +## Retrieve all scheduled sends -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +**This endpoint allows you to retrieve all cancel/paused scheduled send information.** -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| id | integer | ID of the domain whitelabel to delete the IP from. | -| ip | string | IP to remove from the domain whitelabel. | +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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. -### DELETE /whitelabel/domains/{id}/ips/{ip} +### GET /user/scheduled_sends ```javascript - const data = None; - request.body = data; - request.method = 'DELETE'; - request.url = '/v3/whitelabel/domains/{id}/ips/{ip}'; + request.method = 'GET'; + request.url = '/v3/user/scheduled_sends'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Validate a domain whitelabel. - -**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 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. +## Delete a cancellation or pause of a scheduled send -For more information on whitelabeling, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) +**This endpoint allows you to delete the cancellation/pause of a scheduled send.** -## URI Parameters -| URI Parameter | Type | Description | -|---|---|---| -| id | integer |ID of the domain whitelabel to validate. | +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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. -### POST /whitelabel/domains/{id}/validate +### DELETE /user/scheduled_sends/{batch_id} ```javascript const data = None; request.body = data; - request.method = 'POST'; - request.url = '/v3/whitelabel/domains/{id}/validate'; + request.method = 'DELETE'; + request.url = '/v3/user/scheduled_sends/{batch_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Create an IP whitelabel - -**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. +## Update user scheduled send information -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 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/ips.html). +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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. -### POST /whitelabel/ips +### PATCH /user/scheduled_sends/{batch_id} ```javascript const data = { - "domain": "example.com", - "ip": "192.168.1.1", - "subdomain": "email" + "status": "pause" }; request.body = data; - request.method = 'POST'; - request.url = '/v3/whitelabel/ips'; + request.method = 'PATCH'; + request.url = '/v3/user/scheduled_sends/{batch_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all IP whitelabels - -**This endpoint allows you to retrieve all of the IP whitelabels that have been created 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."). +## Retrieve scheduled send -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 the cancel/paused scheduled send information for a specific `batch_id`.** -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). +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 canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. -### GET /whitelabel/ips +### GET /user/scheduled_sends/{batch_id} ```javascript - const queryParams = { - 'ip': 'test_string', - 'limit': 1, - 'offset': 1 -}; - request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/whitelabel/ips'; + request.url = '/v3/user/scheduled_sends/{batch_id}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete an IP whitelabel +## Update Enforced TLS settings -**This endpoint allows you to delete an IP whitelabel.** +**This endpoint allows you to update your current Enforced TLS settings.** -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. +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. -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). +**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. -### DELETE /whitelabel/ips/{id} +### PATCH /user/settings/enforced_tls ```javascript - const data = None; + const data = { + "require_tls": true, + "require_valid_cert": false +}; request.body = data; - request.method = 'DELETE'; - request.url = '/v3/whitelabel/ips/{id}'; + request.method = 'PATCH'; + request.url = '/v3/user/settings/enforced_tls'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve an IP whitelabel +## Retrieve current Enforced TLS settings. -**This endpoint allows you to retrieve an IP whitelabel.** +**This endpoint allows you to retrieve your current Enforced TLS settings.** -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. +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. -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). +**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. -### GET /whitelabel/ips/{id} +### GET /user/settings/enforced_tls ```javascript request.method = 'GET'; - request.url = '/v3/whitelabel/ips/{id}'; + request.url = '/v3/user/settings/enforced_tls'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Validate an IP whitelabel +## Update your username + +**This endpoint allows you to update the username for your account.** -**This endpoint allows you to validate an IP whitelabel.** +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -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 about your user profile: -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) -### POST /whitelabel/ips/{id}/validate +### PUT /user/username ```javascript - const data = None; + const data = { + "username": "test_username" +}; request.body = data; - request.method = 'POST'; - request.url = '/v3/whitelabel/ips/{id}/validate'; + request.method = 'PUT'; + request.url = '/v3/user/username'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Create a Link Whitelabel +## Retrieve your username + +**This endpoint allows you to retrieve your current account username.** -**This endpoint allows you to create a new link whitelabel.** +Keeping your user profile up to date is essential. This will help SendGrid to verify who you are as well as contact you should we need to. -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 about your user profile: -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +* [SendGrid Account Settings](https://sendgrid.com/docs/User_Guide/Settings/account.html) -### POST /whitelabel/links +### GET /user/username ```javascript - const data = { - "default": true, - "domain": "example.com", - "subdomain": "mail" -}; - request.body = data; - const queryParams = { - 'limit': 1, - 'offset': 1 -}; - request.qs = queryParams; - request.method = 'POST'; - request.url = '/v3/whitelabel/links'; + request.method = 'GET'; + request.url = '/v3/user/username'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve all link whitelabels +## Update Event Notification Settings -**This endpoint allows you to retrieve all link whitelabels.** +**This endpoint allows you to update your current event webhook settings.** -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 event type is marked as `true`, then the event webhook will include information about that event. -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. -### GET /whitelabel/links +Typical 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. + +### PATCH /user/webhooks/event/settings ```javascript - const queryParams = { - 'limit': 1 + const data = { + "bounce": true, + "click": true, + "deferred": true, + "delivered": true, + "dropped": true, + "enabled": true, + "group_resubscribe": true, + "group_unsubscribe": true, + "open": true, + "processed": true, + "spam_report": true, + "unsubscribe": true, + "url": "url" }; - request.qs = queryParams; - request.method = 'GET'; - request.url = '/v3/whitelabel/links'; + request.body = data; + request.method = 'PATCH'; + request.url = '/v3/user/webhooks/event/settings'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a Default Link Whitelabel +## Retrieve Event Webhook settings -**This endpoint allows you to retrieve the default link whitelabel.** +**This endpoint allows you to retrieve your current event webhook settings.** -Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the following order will determine the default: -
    -
  • Validated link whitelabels marked as "default"
    • -
  • Legacy link whitelabels (migrated from the whitelabel wizard)
    • -
  • Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net)
    • -
+If an event type is marked as `true`, then the event webhook will include information about that event. -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. +SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +Typical 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. -### GET /whitelabel/links/default +### GET /user/webhooks/event/settings ```javascript - const queryParams = { - 'domain': 'test_string' -}; - request.qs = queryParams; request.method = 'GET'; - request.url = '/v3/whitelabel/links/default'; + request.url = '/v3/user/webhooks/event/settings'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Disassociate a Link Whitelabel - -**This endpoint allows you to disassociate a link whitelabel from a subuser.** +## Test Event Notification Settings -Link whitelables can be associated with subusers from the parent account. This functionality allows -subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account -must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. +**This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL.** -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. +SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +Typical 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. -### DELETE /whitelabel/links/subuser +### POST /user/webhooks/event/test ```javascript - const data = None; - request.body = data; - const queryParams = { - 'username': 'test_string' + const data = { + "url": "url" }; - request.qs = queryParams; - request.method = 'DELETE'; - request.url = '/v3/whitelabel/links/subuser'; + request.body = data; + request.method = 'POST'; + request.url = '/v3/user/webhooks/event/test'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve Associated Link Whitelabel - -**This endpoint allows you to retrieve the associated link whitelabel for a subuser.** - -Link whitelables can be associated with subusers from the parent account. This functionality allows -subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account -must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. +## Create a parse setting -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 create a new inbound parse setting.** -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). -### GET /whitelabel/links/subuser +### POST /user/webhooks/parse/settings ```javascript - const queryParams = { - 'username': 'test_string' + const data = { + "hostname": "myhostname.com", + "send_raw": false, + "spam_check": true, + "url": "http://email.myhosthame.com" }; - request.qs = queryParams; - request.method = 'GET'; - request.url = '/v3/whitelabel/links/subuser'; + request.body = data; + request.method = 'POST'; + request.url = '/v3/user/webhooks/parse/settings'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Delete a Link Whitelabel - -**This endpoint allows you to delete a link whitelabel.** +## Retrieve all parse settings -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 retrieve all of your current inbound parse settings.** -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). -### DELETE /whitelabel/links/{id} +### GET /user/webhooks/parse/settings ```javascript - const data = None; - request.body = data; - request.method = 'DELETE'; - request.url = '/v3/whitelabel/links/{id}'; + request.method = 'GET'; + request.url = '/v3/user/webhooks/parse/settings'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Update a Link Whitelabel - -**This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status.** +## Delete a parse setting -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 delete a specific inbound parse setting.** -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). -### PATCH /whitelabel/links/{id} +### DELETE /user/webhooks/parse/settings/{hostname} ```javascript - const data = { - "default": true -}; + const data = None; request.body = data; - request.method = 'PATCH'; - request.url = '/v3/whitelabel/links/{id}'; + request.method = 'DELETE'; + request.url = '/v3/user/webhooks/parse/settings/{hostname}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Retrieve a Link Whitelabel - -**This endpoint allows you to retrieve a specific link whitelabel.** +## Update a parse setting -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 a specific inbound parse setting.** -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). -### GET /whitelabel/links/{id} +### PATCH /user/webhooks/parse/settings/{hostname} ```javascript - request.method = 'GET'; - request.url = '/v3/whitelabel/links/{id}'; + const data = { + "send_raw": true, + "spam_check": false, + "url": "http://newdomain.com/parse" +}; + request.body = data; + request.method = 'PATCH'; + request.url = '/v3/user/webhooks/parse/settings/{hostname}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Validate a Link Whitelabel - -**This endpoint allows you to validate a link whitelabel.** +## Retrieve a specific parse setting -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 retrieve a specific inbound parse setting.** -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Webhooks/parse.html). -### POST /whitelabel/links/{id}/validate +### GET /user/webhooks/parse/settings/{hostname} ```javascript - const data = None; - request.body = data; - request.method = 'POST'; - request.url = '/v3/whitelabel/links/{id}/validate'; + request.method = 'GET'; + request.url = '/v3/user/webhooks/parse/settings/{hostname}'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` -## Associate a Link Whitelabel - -**This endpoint allows you to associate a link whitelabel with a subuser account.** +## Retrieves Inbound Parse Webhook statistics. -Link whitelables can be associated with subusers from the parent account. This functionality allows -subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account -must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. +**This endpoint allows you to retrieve the statistics for your Parse Webhook usage.** -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. +SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incoming 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. -For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/links.html). +There are many 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). -### POST /whitelabel/links/{link_id}/subuser +### GET /user/webhooks/parse/stats ```javascript - const data = { - "username": "jane@example.com" + const queryParams = { + 'aggregated_by': 'day', + 'end_date': '2016-04-01', + 'limit': 'test_string', + 'offset': 'test_string', + 'start_date': '2016-01-01' }; - request.body = data; - request.method = 'POST'; - request.url = '/v3/whitelabel/links/{link_id}/subuser'; + request.qs = queryParams; + request.method = 'GET'; + request.url = '/v3/user/webhooks/parse/stats'; client.request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) ``` - diff --git a/packages/client/USE_CASES.md b/packages/client/USE_CASES.md index 5aec12326..2b5bfa7b1 100644 --- a/packages/client/USE_CASES.md +++ b/packages/client/USE_CASES.md @@ -2,17 +2,17 @@ This document provides examples for specific SendGrid v3 API non-mail/send use c # Table of Contents -* [How to Setup a Domain Whitelabel](#domain-white-label) +* [How to Setup a Domain Authentication](#domain-authentication) * [How to View Email Statistics](#email-stats) * [How to use the Email Activity Feed](#email-activity-feed) - -# How to Setup a Domain Whitelabel + +# How to Setup a Domain Authentication -You can find documentation for how to setup a domain whitelabel via the UI [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/setup_domain_whitelabel.html) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#whitelabel). +You can find documentation for how to setup a domain authentication via the UI [here](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#sender-authentication). -Find more information about all of SendGrid's whitelabeling related documentation [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/index.html). +Find more information about all of SendGrid's authentication related documentation [here](https://sendgrid.com/docs/ui/account-and-settings/). # How to View Email Statistics diff --git a/packages/mail/USE_CASES.md b/packages/mail/USE_CASES.md index 695f9ee19..56ae5c869 100644 --- a/packages/mail/USE_CASES.md +++ b/packages/mail/USE_CASES.md @@ -22,7 +22,7 @@ This documentation provides examples for specific email use cases. Please [open * [Deploy a Simple App on Google App Engine with Node.js](#gae) * [Deploy a Simple App on Heroku with Node.js](#heroku) * [How to Setup Email Sending on Azure](#send_via_azure) -* [How to Setup a Domain Whitelabel](#domain-white-label) +* [How to Setup a Domain Authentication](#domain-authentication) * [How to View Email Statistics](#email-stats) * [Slack event integration](#slackeventintegration) @@ -825,12 +825,12 @@ This will enable you to send a simple message to be sent to your email. 9. Now as soon as you deploy your application, it will run on the aforementioned port. You will again receive a message in your inbox. 10. And Voila you have your app deployed and sending Emails via Azure. Now you can chain your custom logic if you need to send emails as per some parameters and to specific people as per your requirement. - -# How to Setup a Domain Whitelabel + +# How to Setup a Domain authentication -You can find documentation for how to setup a domain whitelabel via the UI [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/setup_domain_whitelabel.html) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#whitelabel). +You can find documentation for how to setup a domain authentication via the UI [here](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#sender-authentication). -Find more information about all of SendGrid's whitelabeling related documentation [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/index.html). +Find more information about all of SendGrid's authentication related documentation [here](https://sendgrid.com/docs/ui/account-and-settings/). # How to View Email Statistics diff --git a/use-cases/README.md b/use-cases/README.md index 907178ad3..3a30bcdb9 100644 --- a/use-cases/README.md +++ b/use-cases/README.md @@ -20,5 +20,5 @@ This documentation provides examples for specific SendGrid v3 API use cases. Ple * [Kitchen Sink - an example with all settings used](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/kitchen-sink.md) # Non-mail Use Cases -* [How to Setup a Domain Whitelabel](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/domain-white-label.md) +* [How to Setup a Domain Authentication](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/domain-authentication.md) * [How to View Email Statistics](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/email-stats.md) diff --git a/use-cases/domain-authentication.md b/use-cases/domain-authentication.md new file mode 100644 index 000000000..6c47093f0 --- /dev/null +++ b/use-cases/domain-authentication.md @@ -0,0 +1,5 @@ +# How to Setup a Domain Authentication + +You can find documentation for how to setup a domain authentication via the UI [here](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#sender-authorization). + +Find more information about all of SendGrid's authentication related documentation [here](https://sendgrid.com/docs/ui/account-and-settings/). diff --git a/use-cases/domain-white-label.md b/use-cases/domain-white-label.md deleted file mode 100644 index f754e820c..000000000 --- a/use-cases/domain-white-label.md +++ /dev/null @@ -1,5 +0,0 @@ -# How to Setup a Domain Whitelabel - -You can find documentation for how to setup a domain whitelabel via the UI [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/setup_domain_whitelabel.html) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#whitelabel). - -Find more information about all of SendGrid's whitelabeling related documentation [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/index.html).