+
+2. __[Fork](https://help.github.com/fork-a-repo/)__ the [sendgrid-python](https://github.com/sendgrid/sendgrid-python) repository:
+
+
+
+3. __Clone__ your fork via the following commands:
+
+```bash
+# Clone your fork of the repo into the current directory
+git clone https://github.com/your_username/sendgrid-python
+# Navigate to the newly cloned directory
+cd sendgrid-python
+# Assign the original repo to a remote called "upstream"
+git remote add upstream https://github.com/sendgrid/sendgrid-python
+```
+
+> Don't forget to replace *your_username* in the URL by your real GitHub username.
+
+4. __Create a new topic branch__ (off the main project development branch) to contain your feature, change, or fix:
+
+```bash
+git checkout -b ThanksThe SendGrid Team
", - "text": "Thanks,/n The SendGrid Team" + "html": "ThanksThe Twilio SendGrid Team
", + "text": "Thanks,/n The Twilio SendGrid Team" }, "sandbox_mode": { "enable": False @@ -2257,7 +2258,7 @@ print(response.headers) **This endpoint allows you to retrieve a list of all mail settings.** -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings @@ -2275,7 +2276,7 @@ print(response.headers) The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/address_whitelist @@ -2299,7 +2300,7 @@ print(response.headers) The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/address_whitelist @@ -2314,9 +2315,9 @@ print(response.headers) **This endpoint allows you to update your current BCC mail settings.** -When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. +When the BCC mail setting is enabled, Twilio SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/bcc @@ -2335,9 +2336,9 @@ print(response.headers) **This endpoint allows you to retrieve your current BCC mail settings.** -When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. +When the BCC mail setting is enabled, Twilio SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/bcc @@ -2352,9 +2353,9 @@ print(response.headers) **This endpoint allows you to update your current bounce purge settings.** -This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. +This setting allows you to set a schedule for Twilio SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/bounce_purge @@ -2374,9 +2375,9 @@ print(response.headers) **This endpoint allows you to retrieve your current bounce purge settings.** -This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. +This setting allows you to set a schedule for Twilio SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/bounce_purge @@ -2393,7 +2394,7 @@ print(response.headers) The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/footer @@ -2415,7 +2416,7 @@ print(response.headers) The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/footer @@ -2432,7 +2433,7 @@ print(response.headers) Activating this setting allows you to specify an email address to which bounce reports are forwarded. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/forward_bounce @@ -2453,7 +2454,7 @@ print(response.headers) Activating this setting allows you to specify an email address to which bounce reports are forwarded. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/forward_bounce @@ -2470,7 +2471,7 @@ print(response.headers) Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/forward_spam @@ -2491,7 +2492,7 @@ print(response.headers) Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/forward_spam @@ -2508,7 +2509,7 @@ print(response.headers) The plain content setting will automatically convert any plain text emails that you send to HTML before sending. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/plain_content @@ -2528,7 +2529,7 @@ print(response.headers) The plain content setting will automatically convert any plain text emails that you send to HTML before sending. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/plain_content @@ -2545,7 +2546,7 @@ print(response.headers) The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/spam_check @@ -2567,7 +2568,7 @@ print(response.headers) The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/spam_check @@ -2586,7 +2587,7 @@ This setting refers to our original email templates. We currently support more f The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### PATCH /mail_settings/template @@ -2609,7 +2610,7 @@ This setting refers to our original email templates. We currently support more f The legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). +Mail settings allow you to tell Twilio SendGrid specific things to do to every email that you send to your recipients over Twilio SendGrid's [Web API](https://sendgrid.com/docs/API_Reference/Web_API/mail.html) or [SMTP Relay](https://sendgrid.com/docs/API_Reference/SMTP_API/index.html). ### GET /mail_settings/template @@ -2648,7 +2649,7 @@ print(response.headers) **This endpoint allows you to retrieve a list of all partner settings that you can enable.** -Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). +Our partner settings allow you to integrate your Twilio SendGrid account with our partners to increase your Twilio SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). ### GET /partner_settings @@ -2664,9 +2665,9 @@ print(response.headers) **This endpoint allows you to update or change your New Relic partner settings.** -Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). +Our partner settings allow you to integrate your Twilio SendGrid account with our partners to increase your Twilio SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). -By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). +By integrating with New Relic, you can send your Twilio SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). ### PATCH /partner_settings/new_relic @@ -2686,9 +2687,9 @@ print(response.headers) **This endpoint allows you to retrieve your current New Relic partner settings.** -Our partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). +Our partner settings allow you to integrate your Twilio SendGrid account with our partners to increase your Twilio SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/partners.html). -By integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). +By integrating with New Relic, you can send your Twilio SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [Classroom](https://sendgrid.com/docs/Classroom/Track/Collecting_Data/new_relic.html). ### GET /partner_settings/new_relic @@ -2706,7 +2707,7 @@ print(response.headers) **This endpoint returns a list of all scopes that this user has access to.** -API Keys can be used to authenticate the use of [SendGrids v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissions, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). +API Keys can be used to authenticate the use of [Twilio SendGrid's v3 Web API](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html), or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). API Keys may be assigned certain permissions, or scopes, that limit which API endpoints they are able to access. For a more detailed explanation of how you can use API Key permissions, please visit our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/api_keys.html#-API-Key-Permissions) or [Classroom](https://sendgrid.com/docs/Classroom/Basics/API/api_key_permissions.html). ### GET /scopes @@ -2726,7 +2727,7 @@ print(response.headers) *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 @@ -2758,7 +2759,7 @@ print(response.headers) **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 @@ -2773,7 +2774,7 @@ print(response.headers) **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. @@ -2808,7 +2809,7 @@ print(response.headers) **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} @@ -2824,7 +2825,7 @@ print(response.headers) **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} @@ -2840,7 +2841,7 @@ print(response.headers) **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 @@ -2852,2184 +2853,2188 @@ print(response.status_code) print(response.body) print(response.headers) ``` - -# 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 own stats. - -### GET /stats + +# SENDER AUTHENTICATION -```python -params = {'aggregated_by': 'day', 'limit': 1, 'start_date': '2016-01-01', 'end_date': '2016-04-01', 'offset': 1} -response = sg.client.stats.get(query_params=params) -print(response.status_code) -print(response.body) -print(response.headers) -``` - -# SUBUSERS +## Create an authenticated domain. -## Create Subuser +**This endpoint allows you to create a domain 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 a domain authentication on behalf of your subuser. This means the subuser is able to see and modify the created authentication. +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 domain authentication, but will not be able to see or modify that authentication. However, if the subuser creates their own 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) -### POST /subusers +### POST /whitelabel/domains ```python 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" } -response = sg.client.subusers.post(request_body=data) +response = sg.client.whitelabel.domains.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` -## List all Subusers - -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 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) - -### GET /subusers +## List all domain authentications. +**This endpoint allows you to retrieve a list of all domain authentications you have created.** -```python -params = {'username': 'test_string', 'limit': 1, 'offset': 1} -response = sg.client.subusers.get(query_params=params) -print(response.status_code) -print(response.body) -print(response.headers) -``` -## Retrieve Subuser Reputations +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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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. -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 negative action happens on a sent email, it will effect your sender rating. +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) -This endpoint allows you to request the reputations for your subusers. -### GET /subusers/reputations +### GET /whitelabel/domains ```python -params = {'usernames': 'test_string'} -response = sg.client.subusers.reputations.get(query_params=params) +params = {'username': 'test_string', 'domain': 'test_string', 'exclude_subusers': 'true', 'limit': 1, 'offset': 1} +response = sg.client.whitelabel.domains.get(query_params=params) print(response.status_code) print(response.body) print(response.headers) ``` -## 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 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) -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 authentication for. | -### GET /subusers/stats +### GET /whitelabel/domains/default ```python -params = {'end_date': '2016-04-01', 'aggregated_by': 'day', 'limit': 1, 'offset': 1, 'start_date': '2016-01-01', 'subusers': 'test_string'} -response = sg.client.subusers.stats.get(query_params=params) +response = sg.client.whitelabel.domains.default.get() print(response.status_code) print(response.body) print(response.headers) ``` -## Retrieve monthly stats for all subusers +## List the domain authentication associated with the 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 retrieve all of the domain authentications that have been assigned to 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. +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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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 default authentication and validate it. The parent may then associate the default 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/User_Guide/Settings/Whitelabel/index.html) -### GET /subusers/stats/monthly +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| username | string | Username of the subuser to find associated domain authentications for. | + +### GET /whitelabel/domains/subuser ```python -params = {'subuser': 'test_string', 'limit': 1, 'sort_by_metric': 'test_string', 'offset': 1, 'date': 'test_string', 'sort_by_direction': 'asc'} -response = sg.client.subusers.stats.monthly.get(query_params=params) +response = sg.client.whitelabel.domains.subuser.get() print(response.status_code) print(response.body) print(response.headers) ``` -## Retrieve the totals for each email statistic metric for all subusers. +## Disassociate a domain authentication from a 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 disassociate a specific default authentication from a 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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 default authentication and validate it. The parent may then associate the default 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/User_Guide/Settings/Whitelabel/index.html) -### GET /subusers/stats/sums +## URI Parameters +| URI Parameter | Type | Required? | Description | +|---|---|---|---| +| username | string | required | Username for the subuser to find associated domain authentications for. | + +### DELETE /whitelabel/domains/subuser ```python -params = {'end_date': '2016-04-01', 'aggregated_by': 'day', 'limit': 1, 'sort_by_metric': 'test_string', 'offset': 1, 'start_date': '2016-01-01', 'sort_by_direction': 'asc'} -response = sg.client.subusers.stats.sums.get(query_params=params) +response = sg.client.whitelabel.domains.subuser.delete() print(response.status_code) print(response.body) print(response.headers) ``` -## 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) -### PATCH /subusers/{subuser_name} +### PATCH /whitelabel/domains/{domain_id} ```python data = { - "disabled": False + "custom_spf": True, + "default": False } -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).patch(request_body=data) +domain_id = "test_url_param" +response = sg.client.whitelabel.domains._(domain_id).patch(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` -## Delete a subuser +## Retrieve a domain authentication. -This endpoint allows you to delete a subuser. This is a permanent action, once you delete a subuser it cannot be retrieved. +**This endpoint allows you to retrieve a specific 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) -### DELETE /subusers/{subuser_name} + +### GET /whitelabel/domains/{domain_id} ```python -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).delete() +domain_id = "test_url_param" +response = sg.client.whitelabel.domains._(domain_id).get() print(response.status_code) print(response.body) print(response.headers) ``` -## Update IPs assigned to a subuser +## Delete 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 delete a 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) -### PUT /subusers/{subuser_name}/ips +### DELETE /whitelabel/domains/{domain_id} ```python -data = [ - "127.0.0.1" -] -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).ips.put(request_body=data) +domain_id = "test_url_param" +response = sg.client.whitelabel.domains._(domain_id).delete() print(response.status_code) print(response.body) print(response.headers) ``` -## 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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 default authentication and validate it. The parent may then associate the default authentication via the subuser management tools. + +For more information on domain authentication, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Settings/Whitelabel/index.html) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| domain_id | integer | ID of the domain authentication to associate with the subuser. | + +### POST /whitelabel/domains/{domain_id}/subuser ```python data = { - "email": "example@example.com", - "frequency": 500 + "username": "jane@example.com" } -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.put(request_body=data) +domain_id = "test_url_param" +response = sg.client.whitelabel.domains._(domain_id).subuser.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` -## 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| id | integer | ID of the domain to which you are adding an IP | + +### POST /whitelabel/domains/{id}/ips ```python data = { - "email": "example@example.com", - "frequency": 50000 + "ip": "192.168.0.1" } -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.post(request_body=data) +id = "test_url_param" +response = sg.client.whitelabel.domains._(id).ips.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` -## Retrieve monitor settings for a subuser +## 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.** -### 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| id | integer | ID of the domain authentication to delete the IP from. | +| ip | string | IP to remove from the domain authentication. | + +### DELETE /whitelabel/domains/{id}/ips/{ip} ```python -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.get() +id = "test_url_param" +ip = "test_url_param" +response = sg.client.whitelabel.domains._(id).ips._(ip).delete() print(response.status_code) print(response.body) print(response.headers) ``` -## Delete monitor settings +## 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 default authentication could not be validated.** -### 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 personal sending domain. You will be required to create a subdomain so that Twilio SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, Twilio 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/User_Guide/Settings/Whitelabel/index.html) + +## URI Parameters +| URI Parameter | Type | Description | +|---|---|---| +| id | integer |ID of the domain authentication to validate. | + +### POST /whitelabel/domains/{id}/validate ```python -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.delete() +id = "test_url_param" +response = sg.client.whitelabel.domains._(id).validate.post() print(response.status_code) print(response.body) print(response.headers) ``` -## Retrieve the monthly email statistics for a single subuser -**This endpoint allows you to retrieve the monthly email statistics for a specific subuser.** +## Create reverse DNS 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 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. +**This endpoint allows you to create a reverse DNS 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`. +When creating a reverse DNS record, you should use the same subdomain that you used when you created a domain authentication. -For more information, see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/subuser.html). +Reverse DNS consists of a subdomain and domain that will be used to generate a record for a given IP. Once Twilio 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 /subusers/{subuser_name}/stats/monthly +For more information, please see our [User Guide](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/). + +### POST /whitelabel/ips ```python -params = {'date': 'test_string', 'sort_by_direction': 'asc', 'limit': 1, 'sort_by_metric': 'test_string', 'offset': 1} -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).stats.monthly.get(query_params=params) +data = { + "domain": "example.com", + "ip": "192.168.1.1", + "subdomain": "email" +} +response = sg.client.whitelabel.ips.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` - -# SUPPRESSION -## 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.** -[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. +You 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 Twilio 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 ```python -params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} -response = sg.client.suppression.blocks.get(query_params=params) +params = {'ip': 'test_string', 'limit': 1, 'offset': 1} +response = sg.client.whitelabel.ips.get(query_params=params) print(response.status_code) print(response.body) print(response.headers) ``` -## Delete blocks +## Retrieve a reverse DNS record -**This endpoint allows you to delete all email addresses on your blocks list.** +**This endpoint allows you to retrieve a reverse DNS record.** -There are two options for deleting blocked emails: +A reverse DNS record consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once Twilio SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. -1. You can delete all blocked emails by setting `delete_all` to true in the request body. -2. You can delete some blocked emails by specifying the email addresses in an array in the request body. - -[Blocks](https://sendgrid.com/docs/Glossary/blocks.html) happen when your message was rejected for a reason related to the message, not the recipient address. This can happen when your mail server IP address has been added to a blacklist or blocked by an ISP, or if the message content is flagged by a filter on the receiving server. - -For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/blocks.html). +For more information, please see our [User Guide](https://sendgrid.com/docs/API_Reference/Web_API_v3/Whitelabel/ips.html). -### DELETE /suppression/blocks +### GET /whitelabel/ips/{id} ```python -data = { - "delete_all": False, - "emails": [ - "example1@example.com", - "example2@example.com" - ] -} -response = sg.client.suppression.blocks.delete(request_body=data) +id = "test_url_param" +response = sg.client.whitelabel.ips._(id).get() print(response.status_code) print(response.body) print(response.headers) ``` -## Retrieve a specific block +## Delete a reverse DNS record -**This endpoint allows you to retrieve a specific email address from your blocks list.** +**This endpoint allows you to delete a 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 the message content is flagged by a filter on the receiving server. +A reverse DNS record consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once Twilio 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/API_Reference/Web_API_v3/Whitelabel/ips.html). -### GET /suppression/blocks/{email} +### DELETE /whitelabel/ips/{id} ```python -email = "test_url_param" -response = sg.client.suppression.blocks._(email).get() +id = "test_url_param" +response = sg.client.whitelabel.ips._(id).delete() print(response.status_code) print(response.body) print(response.headers) ``` -## Delete a specific block +## Validate a reverse DNS record -**This endpoint allows you to delete a specific email address from your blocks list.** +**This endpoint allows you to validate a 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 the message content is flagged by a filter on the receiving server. +A reverse DNS record consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once Twilio 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/API_Reference/Web_API_v3/Whitelabel/ips.html). -### DELETE /suppression/blocks/{email} +### POST /whitelabel/ips/{id}/validate ```python -email = "test_url_param" -response = sg.client.suppression.blocks._(email).delete() +id = "test_url_param" +response = sg.client.whitelabel.ips._(id).validate.post() print(response.status_code) print(response.body) print(response.headers) ``` -## Retrieve all bounces - -**This endpoint allows you to retrieve all of your bounces.** +## Create a Link Branding -Bounces are messages that are returned to the server that sent it. +**This endpoint allows you to create a new link branding.** -For more information see: +Email link brandings 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/API_Reference/Web_API_v3/Whitelabel/links.html). -### GET /suppression/bounces +### POST /whitelabel/links ```python -params = {'start_time': 1, 'end_time': 1} -response = sg.client.suppression.bounces.get(query_params=params) +data = { + "default": True, + "domain": "example.com", + "subdomain": "mail" +} +params = {'limit': 1, 'offset': 1} +response = sg.client.whitelabel.links.post(request_body=data, query_params=params) print(response.status_code) print(response.body) print(response.headers) ``` -## 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.** - -Bounces are messages that are returned to the server that sent it. +## Retrieve all link brandings -For more information see: +**This endpoint allows you to retrieve all link brandings.** -* [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) +Email link brandings allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. -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/API_Reference/Web_API_v3/Whitelabel/links.html). -### DELETE /suppression/bounces +### GET /whitelabel/links ```python -data = { - "delete_all": True, - "emails": [ - "example@example.com", - "example2@example.com" - ] -} -response = sg.client.suppression.bounces.delete(request_body=data) +params = {'limit': 1} +response = sg.client.whitelabel.links.get(query_params=params) print(response.status_code) print(response.body) print(response.headers) ``` -## 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.** -Bounces are messages that are 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: +-
+
- Validated link brandings marked as "default" +
- Legacy link brands (migrated from the whitelabel wizard) +
- Default Twilio SendGrid link branding (i.e. 100.ct.sendgrid.net) +
-
-
- Validated link whitelabels marked as "default" -
- Legacy link whitelabels (migrated from the whitelabel wizard) -
- Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net) -
Hello, {{name}}! Your current balance is {{balance}}
- - """ - mail = Mail() - mail.from_email = Email('templates@sendgrid.com') - mail.template_id = 'd-your-dynamic-template-uid' - p = Personalization() - p.add_to(Email('user@example.com')) - p.dynamic_template_data = { - 'name': 'Bob', - 'balance': 42 - } - mail.add_personalization(p) - - sg = SendGridAPIClient() - response = sg.client.mail.send.post(request_body=mail.get()) - print(response.status_code) - print(response.headers) - print(response.body) ->>>>>>> master:examples/helpers/mail_example.py diff --git a/examples/helpers/stats/stats_example.py b/examples/helpers/stats/stats_example.py index f3196881a..f22baa5c4 100644 --- a/examples/helpers/stats/stats_example.py +++ b/examples/helpers/stats/stats_example.py @@ -3,11 +3,11 @@ from sendgrid.helpers.stats import * from sendgrid import * -# NOTE: you will need move this file to the root directory of this project to execute properly. +# NOTE: you will need to move this file to the root directory of this project to execute properly. # Assumes you set your environment variable: -# https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key -sg = SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +# See: https://github.com/sendgrid/sendgrid-python/blob/HEAD/TROUBLESHOOTING.md#environment-variables-and-your-sendgrid-api-key +sg = SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) def pprint_json(json_raw): diff --git a/examples/ips/ips.py b/examples/ips/ips.py index 5d3e4e0bd..316d0c858 100644 --- a/examples/ips/ips.py +++ b/examples/ips/ips.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Retrieve all IP addresses # diff --git a/examples/mail/mail.py b/examples/mail/mail.py index b04304ec8..d2ccc80f0 100644 --- a/examples/mail/mail.py +++ b/examples/mail/mail.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Create a batch ID # @@ -28,7 +27,7 @@ # v3 Mail Send # # POST /mail/send # # This endpoint has a helper, check it out -# [here](https://github.com/sendgrid/sendgrid-python/blob/master/use_cases/README.md). +# [here](https://github.com/sendgrid/sendgrid-python/blob/HEAD/use_cases/README.md). data = { "asm": { diff --git a/examples/mailboxproviders/mailboxproviders.py b/examples/mailboxproviders/mailboxproviders.py index a95b388b4..4fbf470e2 100644 --- a/examples/mailboxproviders/mailboxproviders.py +++ b/examples/mailboxproviders/mailboxproviders.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Retrieve email statistics by mailbox provider. # diff --git a/examples/mailsettings/mailsettings.py b/examples/mailsettings/mailsettings.py index e0d89b5fa..a4d46e399 100644 --- a/examples/mailsettings/mailsettings.py +++ b/examples/mailsettings/mailsettings.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Retrieve all mail settings # diff --git a/examples/partnersettings/partnersettings.py b/examples/partnersettings/partnersettings.py index fa2589b55..d3675a6ba 100644 --- a/examples/partnersettings/partnersettings.py +++ b/examples/partnersettings/partnersettings.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Returns a list of all partner settings. # diff --git a/examples/scopes/scopes.py b/examples/scopes/scopes.py index c9d4f1209..99519dc3e 100644 --- a/examples/scopes/scopes.py +++ b/examples/scopes/scopes.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Retrieve a list of scopes for which this user has access. # diff --git a/examples/senderauthentication/senderauthentication.py b/examples/senderauthentication/senderauthentication.py index 99efc1b8b..f842d9302 100644 --- a/examples/senderauthentication/senderauthentication.py +++ b/examples/senderauthentication/senderauthentication.py @@ -3,10 +3,10 @@ import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## -# Create a domain whitelabel. # +# Create a domain authentication. # # POST /whitelabel/domains # data = { @@ -27,7 +27,7 @@ print(response.headers) ################################################## -# List all domain whitelabels. # +# List all domain authentications. # # GET /whitelabel/domains # params = {'username': 'test_string', 'domain': 'test_string', @@ -38,7 +38,7 @@ print(response.headers) ################################################## -# Get the default domain whitelabel. # +# Get the default domain authentication. # # GET /whitelabel/domains/default # response = sg.client.whitelabel.domains.default.get() @@ -47,7 +47,7 @@ print(response.headers) ################################################## -# List the domain whitelabel associated with the given user. # +# List the domain authentication associated with the given user. # # GET /whitelabel/domains/subuser # response = sg.client.whitelabel.domains.subuser.get() @@ -56,7 +56,7 @@ print(response.headers) ################################################## -# Disassociate a domain whitelabel from a given user. # +# Disassociate a domain authentication from a given user. # # DELETE /whitelabel/domains/subuser # response = sg.client.whitelabel.domains.subuser.delete() @@ -65,7 +65,7 @@ print(response.headers) ################################################## -# Update a domain whitelabel. # +# Update a domain authentication. # # PATCH /whitelabel/domains/{domain_id} # data = { @@ -79,7 +79,7 @@ print(response.headers) ################################################## -# Retrieve a domain whitelabel. # +# Retrieve a domain authentication. # # GET /whitelabel/domains/{domain_id} # domain_id = "test_url_param" @@ -89,7 +89,7 @@ print(response.headers) ################################################## -# Delete a domain whitelabel. # +# Delete a domain authentication. # # DELETE /whitelabel/domains/{domain_id} # domain_id = "test_url_param" @@ -99,7 +99,7 @@ print(response.headers) ################################################## -# Associate a domain whitelabel with a given user. # +# Associate a domain authentication with a given user. # # POST /whitelabel/domains/{domain_id}/subuser # data = { @@ -113,7 +113,7 @@ print(response.headers) ################################################## -# Add an IP to a domain whitelabel. # +# Add an IP to a domain authentication. # # POST /whitelabel/domains/{id}/ips # data = { @@ -126,7 +126,7 @@ print(response.headers) ################################################## -# Remove an IP from a domain whitelabel. # +# Remove an IP from a domain authentication. # # DELETE /whitelabel/domains/{id}/ips/{ip} # id_ = "test_url_param" @@ -137,7 +137,7 @@ print(response.headers) ################################################## -# Validate a domain whitelabel. # +# Validate a domain authentication. # # POST /whitelabel/domains/{id}/validate # id_ = "test_url_param" @@ -147,7 +147,7 @@ print(response.headers) ################################################## -# Create an IP whitelabel # +# Create a reverse DNS record # # POST /whitelabel/ips # data = { @@ -161,7 +161,7 @@ print(response.headers) ################################################## -# Retrieve all IP whitelabels # +# Create a reverse DNS record # # GET /whitelabel/ips # params = {'ip': 'test_string', 'limit': 1, 'offset': 1} @@ -171,7 +171,7 @@ print(response.headers) ################################################## -# Retrieve an IP whitelabel # +# Retrieve a reverse DNS record # # GET /whitelabel/ips/{id} # id_ = "test_url_param" @@ -181,7 +181,7 @@ print(response.headers) ################################################## -# Delete an IP whitelabel # +# Delete a reverse DNS record # # DELETE /whitelabel/ips/{id} # id_ = "test_url_param" @@ -191,7 +191,7 @@ print(response.headers) ################################################## -# Validate an IP whitelabel # +# Validate a reverse DNS record # # POST /whitelabel/ips/{id}/validate # id_ = "test_url_param" @@ -201,7 +201,7 @@ print(response.headers) ################################################## -# Create a Link Whitelabel # +# Create a Link Branding # # POST /whitelabel/links # data = { @@ -217,7 +217,7 @@ print(response.headers) ################################################## -# Retrieve all link whitelabels # +# Retrieve all link brandings # # GET /whitelabel/links # params = {'limit': 1} @@ -227,7 +227,7 @@ print(response.headers) ################################################## -# Retrieve a Default Link Whitelabel # +# Retrieve a Default Link Branding # # GET /whitelabel/links/default # params = {'domain': 'test_string'} @@ -237,7 +237,7 @@ print(response.headers) ################################################## -# Retrieve Associated Link Whitelabel # +# Retrieve Associated Link Branding # # GET /whitelabel/links/subuser # params = {'username': 'test_string'} @@ -247,7 +247,7 @@ print(response.headers) ################################################## -# Disassociate a Link Whitelabel # +# Disassociate a Link Branding # # DELETE /whitelabel/links/subuser # params = {'username': 'test_string'} @@ -257,7 +257,7 @@ print(response.headers) ################################################## -# Update a Link Whitelabel # +# Update a Link Branding # # PATCH /whitelabel/links/{id} # data = { @@ -270,7 +270,7 @@ print(response.headers) ################################################## -# Retrieve a Link Whitelabel # +# Retrieve a Link Branding # # GET /whitelabel/links/{id} # id_ = "test_url_param" @@ -280,7 +280,7 @@ print(response.headers) ################################################## -# Delete a Link Whitelabel # +# Delete a Link Branding # # DELETE /whitelabel/links/{id} # id_ = "test_url_param" @@ -290,7 +290,7 @@ print(response.headers) ################################################## -# Validate a Link Whitelabel # +# Validate a Link Branding # # POST /whitelabel/links/{id}/validate # id_ = "test_url_param" @@ -300,7 +300,7 @@ print(response.headers) ################################################## -# Associate a Link Whitelabel # +# Associate a Link Branding # # POST /whitelabel/links/{link_id}/subuser # data = { diff --git a/examples/senders/senders.py b/examples/senders/senders.py index f198a8f91..55eb44631 100644 --- a/examples/senders/senders.py +++ b/examples/senders/senders.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Create a Sender Identity # diff --git a/examples/stats/stats.py b/examples/stats/stats.py index 4ddce6b75..cde422447 100644 --- a/examples/stats/stats.py +++ b/examples/stats/stats.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Retrieve global email statistics # diff --git a/examples/subusers/subusers.py b/examples/subusers/subusers.py index 3d79bfb11..0f5ba6fe0 100644 --- a/examples/subusers/subusers.py +++ b/examples/subusers/subusers.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Create Subuser # diff --git a/examples/suppression/suppression.py b/examples/suppression/suppression.py index 391dbe299..430f76f35 100644 --- a/examples/suppression/suppression.py +++ b/examples/suppression/suppression.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Retrieve all blocks # diff --git a/examples/templates/templates.py b/examples/templates/templates.py index a370006b2..9b5210191 100644 --- a/examples/templates/templates.py +++ b/examples/templates/templates.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Create a transactional template. # diff --git a/examples/trackingsettings/trackingsettings.py b/examples/trackingsettings/trackingsettings.py index 0c45e10d9..b3c49f8b2 100644 --- a/examples/trackingsettings/trackingsettings.py +++ b/examples/trackingsettings/trackingsettings.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Retrieve Tracking Settings # diff --git a/examples/user/user.py b/examples/user/user.py index c7aabd4ac..5160f9ff8 100644 --- a/examples/user/user.py +++ b/examples/user/user.py @@ -1,9 +1,8 @@ import sendgrid -import json import os -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +sg = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY')) ################################################## # Get a user's account information. # diff --git a/live_test.py b/live_test.py index 12c52eeed..d666140fb 100644 --- a/live_test.py +++ b/live_test.py @@ -4,8 +4,8 @@ from sendgrid import SendGridAPIClient from sendgrid.helpers.mail import Mail, From, To, Subject, PlainTextContent, HtmlContent, SendGridException -message = Mail(from_email=From('dx@sendgrid.com', 'DX'), - to_emails=To('elmer.thomas@sendgrid.com', 'Elmer Thomas'), +message = Mail(from_email=From('help@twilio.com', 'Twilio SendGrid'), + to_emails=To('ethomas@twilio.com', 'Elmer Thomas'), subject=Subject('Sending with SendGrid is Fun'), plain_text_content=PlainTextContent('and easy to do anywhere, even with Python'), html_content=HtmlContent('and easy to do anywhere, even with Python')) @@ -27,10 +27,10 @@ from sendgrid.helpers.mail import Mail, From, To, Subject, PlainTextContent, HtmlContent, SendGridException to_emails = [ - To('elmer.thomas@sendgrid.com', 'Elmer SendGrid'), + To('ethomas@twilio.com', 'Elmer SendGrid'), To('elmer.thomas@gmail.com', 'Elmer Thomas') ] -message = Mail(from_email=From('dx@sendgrid.com', 'DX'), +message = Mail(from_email=From('help@twilio.com', 'Twilio SendGrid'), to_emails=to_emails, subject=Subject('Sending with SendGrid is Fun'), plain_text_content=PlainTextContent('and easy to do anywhere, even with Python'), @@ -56,10 +56,10 @@ import datetime to_emails = [ - To(email='elmer.thomas@sendgrid.com', - name='Elmer SendGrid', + To(email='ethomas@twilio.com', + name='Elmer Twilio', substitutions={ - Substitution('-name-', 'Elmer SendGrid'), + Substitution('-name-', 'Elmer Twilio'), Substitution('-github-', 'http://github.com/ethomas'), }, subject=Subject('Override Global Subject')), @@ -72,7 +72,7 @@ ] ts = time.time() global_substitutions = Substitution('-time-', datetime.datetime.fromtimestamp(ts).strftime('%Y-%m-%d %H:%M:%S')) -message = Mail(from_email=From('dx@sendgrid.com', 'DX'), +message = Mail(from_email=From('help@twilio.com', 'Twilio SendGrid'), to_emails=to_emails, subject=Subject('Hi -name-'), plain_text_content=PlainTextContent('Hello -name-, your github is -github-, email sent at -time-'), @@ -96,8 +96,8 @@ import json from sendgrid import SendGridAPIClient from sendgrid.helpers.mail import ( - Mail, From, To, Cc, Bcc, Subject, PlainTextContent, - HtmlContent, SendGridException, Substitution, + Mail, From, To, Cc, Bcc, Subject, PlainTextContent, + HtmlContent, SendGridException, Substitution, Header, CustomArg, SendAt, Content, MimeType, Attachment, FileName, FileContent, FileType, Disposition, ContentId, TemplateId, Section, ReplyTo, Category, BatchId, Asm, @@ -114,22 +114,22 @@ message = Mail() -# Define Personalizations +# Define Personalizations message.to = To('elmer+test1@sendgrid.com', 'Example User1', p=0) -message.to = [ +message.to = [ To('elmer+test2@sendgrid.com', 'Example User2', p=0), To('elmer+test3@sendgrid.com', 'Example User3', p=0) ] message.cc = Cc('test4@example.com', 'Example User4', p=0) -message.cc = [ +message.cc = [ Cc('test5@example.com', 'Example User5', p=0), Cc('test6@example.com', 'Example User6', p=0) ] message.bcc = Bcc('test7@example.com', 'Example User7', p=0) -message.bcc = [ +message.bcc = [ Bcc('test8@example.com', 'Example User8', p=0), Bcc('test9@example.com', 'Example User9', p=0) ] @@ -160,19 +160,19 @@ message.send_at = SendAt(1461775051, p=0) message.to = To('test10@example.com', 'Example User10', p=1) -message.to = [ +message.to = [ To('test11@example.com', 'Example User11', p=1), To('test12@example.com', 'Example User12', p=1) ] message.cc = Cc('test13@example.com', 'Example User13', p=1) -message.cc = [ +message.cc = [ Cc('test14@example.com', 'Example User14', p=1), Cc('test15@example.com', 'Example User15', p=1) ] message.bcc = Bcc('test16@example.com', 'Example User16', p=1) -message.bcc = [ +message.bcc = [ Bcc('test17@example.com', 'Example User17', p=1), Bcc('test18@example.com', 'Example User18', p=1) ] @@ -204,9 +204,9 @@ # The values below this comment are global to entire message -message.from_email = From('dx@sendgrid.com', 'DX') +message.from_email = From('help@twilio.com', 'Twilio SendGrid') -message.reply_to = ReplyTo('dx_reply@sendgrid.com', 'DX Reply') +message.reply_to = ReplyTo('help_reply@twilio.com', 'Twilio SendGrid Reply') message.subject = Subject('Sending with SendGrid is Fun 2') @@ -240,7 +240,7 @@ message.section = Section('%section1%', 'Substitution for Section 1 Tag') message.section = [ Section('%section2%', 'Substitution for Section 2 Tag'), - Section('%section3%', 'Substitution for Section 3 Tag') + Section('%section3%', 'Substitution for Section 3 Tag') ] message.header = Header('X-Test9', 'Test9') @@ -284,7 +284,7 @@ tracking_settings.click_tracking = ClickTracking(True, False) tracking_settings.open_tracking = OpenTracking(True, OpenTrackingSubstitutionTag("open_tracking")) tracking_settings.subscription_tracking = SubscriptionTracking( - True, + True, SubscriptionText("Goodbye"), SubscriptionHtml("Goodbye!"), SubscriptionSubstitutionTag("unsubscribe")) @@ -313,8 +313,8 @@ from sendgrid import SendGridAPIClient from sendgrid.helpers.mail import Mail, From, To, Subject, PlainTextContent, HtmlContent, SendGridException, DynamicTemplateData -message = Mail(from_email=From('dx@sendgrid.com', 'DX'), - to_emails=To('elmer.thomas@sendgrid.com', 'Elmer Thomas'), +message = Mail(from_email=From('help@twilio.com', 'Twilio SendGrid'), + to_emails=To('ethomas@twilio.com', 'Elmer Thomas'), subject=Subject('Sending with SendGrid is Fun'), plain_text_content=PlainTextContent('and easy to do anywhere, even with Python'), html_content=HtmlContent('and easy to do anywhere, even with Python')) @@ -354,4 +354,4 @@ print(response.body) print(response.headers) except SendGridException as e: - print(e.message) \ No newline at end of file + print(e.message) diff --git a/proposals/mail-helper-refactor.md b/proposals/mail-helper-refactor.md index 13fefdbd3..70798c262 100644 --- a/proposals/mail-helper-refactor.md +++ b/proposals/mail-helper-refactor.md @@ -2,7 +2,7 @@ # Send a Single Email to a Single Recipient -The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. +The following code assumes you are storing the API key in an [environment variable (recommended)](../TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. This is the minimum code needed to send an email. @@ -18,7 +18,7 @@ message = Mail(from_email=From('from@example.com', 'From Name'), html_content=HtmlContent('and easy to do anywhere, even with Python')) try: - sendgrid_client = SendGridAPIClient(apikey=os.environ.get('SENDGRID_apikey')) + sendgrid_client = SendGridAPIClient(os.environ.get('SENDGRID_apikey')) response = sendgrid_client.send(message=message) print(response.status_code) print(response.body) @@ -29,7 +29,7 @@ except SendGridException as e: # Send a Single Email to Multiple Recipients -The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. +The following code assumes you are storing the API key in an [environment variable (recommended)](../TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. ```python import os @@ -42,12 +42,12 @@ to_emails = [ ] msg = Mail(from_email=From('from@example.com', 'From Name'), to_emails=to_emails, - subject=Subject('Sending with SendGrid is Fun'), + subject=Subject('Sending with Twilio SendGrid is Fun'), plain_text_content=PlainTextContent('and easy to do anywhere, even with Python'), html_content=HtmlContent('and easy to do anywhere, even with Python')) try: - response = sendgrid.send(msg, apikey=os.environ.get('SENDGRID_apikey')) + response = sendgrid.send(msg, os.environ.get('SENDGRID_apikey')) print(response.status_code) print(response.body) print(response.headers) @@ -57,7 +57,7 @@ except Exception as e: # Send Multiple Emails to Multiple Recipients -The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. +The following code assumes you are storing the API key in an [environment variable (recommended)](../TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. ```python import os @@ -90,7 +90,7 @@ msg = Mail(from_email=From('from@example.com', 'From Name'), global_substitutions=global_substitutions) try: - response = sendgrid.send(msg, apikey=os.environ.get('SENDGRID_apikey')) + response = sendgrid.send(msg, os.environ.get('SENDGRID_apikey')) print(response.status_code) print(response.body) print(response.headers) @@ -100,7 +100,7 @@ except Exception as e: # Kitchen Sink - an example with all settings used -The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. +The following code assumes you are storing the API key in an [environment variable (recommended)](../TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. ```python import os @@ -109,7 +109,7 @@ from sendgrid.helpers.mail import * msg = Mail(from_email=From('from@example.com', 'From Name'), to_email=To('to@example.com', 'To Name'), - subject=Subject('Sending with SendGrid is Fun'), + subject=Subject('Sending with Twilio SendGrid is Fun'), plain_text_content=PlainTextContent('and easy to do anywhere, even with Python'), html_content=HtmlContent('and easy to do anywhere, even with Python')) @@ -194,7 +194,7 @@ msg.send_at = SendAt(1461775052, p=1) # The values below this comment are global to the entire message -msg.global_subject = Subject('Sending with SendGrid is Fun') +msg.global_subject = Subject('Sending with Twilio SendGrid is Fun') msg.content = Content(MimeType.Text, 'and easy to do anywhere, even with Python') msg.content = Content(MimeType.Html, 'and easy to do anywhere, even with Python') @@ -236,7 +236,7 @@ msg.section = [ ] try: - response = sendgrid.send(msg, apikey=os.environ.get('SENDGRID_apikey')) + response = sendgrid.send(msg, os.environ.get('SENDGRID_apikey')) print(response.status_code) print(response.body) print(response.headers) @@ -246,7 +246,7 @@ except Exception as e: # Attachments -The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. +The following code assumes you are storing the API key in an [environment variable (recommended)](../TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. ```python import os @@ -255,7 +255,7 @@ from sendgrid.helpers.mail import Mail, From, To, Subject, PlainTextContent, Htm msg = Mail(from_email=From('from@example.com', 'From Name'), to_emails=To('to@example.com', 'To Name'), - subject=Subject('Sending with SendGrid is Fun'), + subject=Subject('Sending with Twilio SendGrid is Fun'), plain_text_content=PlainTextContent('and easy to do anywhere, even with Python'), html_content=HtmlContent('and easy to do anywhere, even with Python')) msg.attachment = Attachment(FileName('balance_001.pdf'), @@ -265,7 +265,7 @@ msg.attachment = Attachment(FileName('balance_001.pdf'), Name('Balance Sheet')) try: - response = sendgrid.send(msg, apikey=os.environ.get('SENDGRID_apikey')) + response = sendgrid.send(msg, os.environ.get('SENDGRID_apikey')) print(response.status_code) print(response.body) print(response.headers) @@ -275,7 +275,7 @@ except Exception as e: # Transactional Templates -The following code assumes you are storing the API key in an [environment variable (recommended)](https://github.com/sendgrid/sendgrid-python/blob/master/TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. +The following code assumes you are storing the API key in an [environment variable (recommended)](../TROUBLESHOOTING.md#environment). If you don't have your key stored in an environment variable, you can assign it directly to `apikey` for testing purposes. For this example, we assume you have created a [transactional template](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). Following is the template content we used for testing. @@ -318,7 +318,7 @@ from sendgrid.helpers.mail import Mail, From, To, Subject, PlainTextContent, Htm msg = Mail(from_email=From('from@example.com', 'From Name'), to_emails=To('to@example.com', 'To Name'), - subject=Subject('Sending with SendGrid is Fun'), + subject=Subject('Sending with Twilio SendGrid is Fun'), plain_text_content=PlainTextContent('and easy to do anywhere, even with Python'), html_content=HtmlContent('and easy to do anywhere, even with Python')) msg.substitution = [ @@ -328,7 +328,7 @@ msg.substitution = [ msg.template_id = TemplateId('13b8f94f-bcae-4ec6-b752-70d6cb59f932') try: - response = sendgrid.send(msg, apikey=os.environ.get('SENDGRID_apikey')) + response = sendgrid.send(msg, os.environ.get('SENDGRID_apikey')) print(response.status_code) print(response.body) print(response.headers) diff --git a/requirements.txt b/requirements.txt index 6ec05dd87..ed2594a90 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ -Flask==1.0.2 +Flask==3.1.0 PyYAML>=4.2b1 -python-http-client==3.1.0 -six==1.11.0 -pytest==3.8.2 +python-http-client>=3.2.1 +six==1.17.0 +cryptography>=45.0.6 +more-itertools==5.0.0 diff --git a/sendgrid/VERSION.txt b/sendgrid/VERSION.txt deleted file mode 100644 index 9b9a24420..000000000 --- a/sendgrid/VERSION.txt +++ /dev/null @@ -1 +0,0 @@ -6.0.2 diff --git a/sendgrid/__init__.py b/sendgrid/__init__.py index 22e4cdc81..cd994dd2f 100644 --- a/sendgrid/__init__.py +++ b/sendgrid/__init__.py @@ -1,10 +1,10 @@ """ -This library allows you to quickly and easily use the SendGrid Web API v3 via +This library allows you to quickly and easily use the Twilio SendGrid Web API v3 via Python. For more information on this library, see the README on GitHub. http://github.com/sendgrid/sendgrid-python -For more information on the SendGrid v3 API, see the v3 docs: +For more information on the Twilio SendGrid v3 API, see the v3 docs: http://sendgrid.com/docs/API_Reference/api_v3.html For the user guide, code examples, and more, visit the main docs page: http://sendgrid.com/docs/index.html @@ -15,13 +15,10 @@ Modules to help with common tasks. """ -import os -from .sendgrid import SendGridAPIClient # noqa -from .helpers.mail import * # noqa from .helpers.endpoints import * # noqa -# from .helpers.inbound import * # noqa +from .helpers.mail import * # noqa from .helpers.stats import * # noqa - -dir_path = os.path.dirname(os.path.realpath(__file__)) -if os.path.isfile(os.path.join(dir_path, 'VERSION.txt')): - __version__ = open(os.path.join(dir_path, 'VERSION.txt')).read().strip() +from .helpers.eventwebhook import * # noqa +from .sendgrid import SendGridAPIClient # noqa +from .twilio_email import TwilioEmailAPIClient # noqa +from .version import __version__ diff --git a/sendgrid/base_interface.py b/sendgrid/base_interface.py new file mode 100644 index 000000000..f94f09479 --- /dev/null +++ b/sendgrid/base_interface.py @@ -0,0 +1,83 @@ +import python_http_client + +region_host_dict = {'eu':'https://api.eu.sendgrid.com','global':'https://api.sendgrid.com'} + +class BaseInterface(object): + def __init__(self, auth, host, impersonate_subuser): + """ + Construct the Twilio SendGrid v3 API object. + Note that the underlying client is being set up during initialization, + therefore changing attributes in runtime will not affect HTTP client + behaviour. + + :param auth: the authorization header + :type auth: string + :param impersonate_subuser: the subuser to impersonate. Will be passed + by "On-Behalf-Of" header by underlying + client. See + https://sendgrid.com/docs/User_Guide/Settings/subusers.html + for more details + :type impersonate_subuser: string + :param host: base URL for API calls + :type host: string + """ + from . import __version__ + self.auth = auth + self.impersonate_subuser = impersonate_subuser + self.version = __version__ + self.useragent = 'sendgrid/{};python'.format(self.version) + self.host = host + + self.client = python_http_client.Client( + host=self.host, + request_headers=self._default_headers, + version=3) + + @property + def _default_headers(self): + """Set the default header for a Twilio SendGrid v3 API call""" + headers = { + "Authorization": self.auth, + "User-Agent": self.useragent, + "Accept": 'application/json' + } + if self.impersonate_subuser: + headers['On-Behalf-Of'] = self.impersonate_subuser + + return headers + + def reset_request_headers(self): + self.client.request_headers = self._default_headers + + def send(self, message): + """Make a Twilio SendGrid v3 API request with the request body generated by + the Mail object + + :param message: The Twilio SendGrid v3 API request body generated by the Mail + object + :type message: Mail + """ + if not isinstance(message, dict): + message = message.get() + + return self.client.mail.send.post(request_body=message) + + def set_sendgrid_data_residency(self, region): + """ + Client libraries contain setters for specifying region/edge. + This supports global and eu regions only. This set will likely expand in the future. + Global is the default residency (or region) + Global region means the message will be sent through https://api.sendgrid.com + EU region means the message will be sent through https://api.eu.sendgrid.com + :param region: string + :return: + """ + if region in region_host_dict.keys(): + self.host = region_host_dict[region] + if self._default_headers is not None: + self.client = python_http_client.Client( + host=self.host, + request_headers=self._default_headers, + version=3) + else: + raise ValueError("region can only be \"eu\" or \"global\"") diff --git a/sendgrid/helpers/eventwebhook/__init__.py b/sendgrid/helpers/eventwebhook/__init__.py new file mode 100644 index 000000000..9d618bf3a --- /dev/null +++ b/sendgrid/helpers/eventwebhook/__init__.py @@ -0,0 +1,56 @@ +from cryptography.exceptions import InvalidSignature +from cryptography.hazmat.primitives import hashes +from cryptography.hazmat.primitives.asymmetric import ec +from cryptography.hazmat.primitives.serialization import load_pem_public_key +import base64 +from .eventwebhook_header import EventWebhookHeader + +class EventWebhook: + """ + This class allows you to use the Event Webhook feature. Read the docs for + more details: https://sendgrid.com/docs/for-developers/tracking-events/event + """ + + def __init__(self, public_key=None): + """ + Construct the Event Webhook verifier object + :param public_key: verification key under Mail Settings + :type public_key: string + """ + self.public_key = self.convert_public_key_to_ecdsa(public_key) if public_key else public_key + + def convert_public_key_to_ecdsa(self, public_key): + """ + Convert the public key string to an EllipticCurvePublicKey object. + + :param public_key: verification key under Mail Settings + :type public_key string + :return: An EllipticCurvePublicKey object using the ECDSA algorithm + :rtype cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey + """ + pem_key = "-----BEGIN PUBLIC KEY-----\n" + public_key + "\n-----END PUBLIC KEY-----" + return load_pem_public_key(pem_key.encode("utf-8")) + + def verify_signature(self, payload, signature, timestamp, public_key=None): + """ + Verify signed event webhook requests. + + :param payload: event payload in the request body + :type payload: string + :param signature: value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header + :type signature: string + :param timestamp: value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header + :type timestamp: string + :param public_key: elliptic curve public key + :type public_key: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey + :return: true or false if signature is valid + """ + timestamped_payload = (timestamp + payload).encode('utf-8') + decoded_signature = base64.b64decode(signature) + + key = public_key or self.public_key + try: + key.verify(decoded_signature, timestamped_payload, ec.ECDSA(hashes.SHA256())) + return True + except InvalidSignature: + return False diff --git a/sendgrid/helpers/eventwebhook/eventwebhook_header.py b/sendgrid/helpers/eventwebhook/eventwebhook_header.py new file mode 100644 index 000000000..a41a48524 --- /dev/null +++ b/sendgrid/helpers/eventwebhook/eventwebhook_header.py @@ -0,0 +1,10 @@ +class EventWebhookHeader: + """ + This class lists headers that get posted to the webhook. Read the docs for + more details: https://sendgrid.com/docs/for-developers/tracking-events/event + """ + SIGNATURE = 'X-Twilio-Email-Event-Webhook-Signature' + TIMESTAMP = 'X-Twilio-Email-Event-Webhook-Timestamp' + + def __init__(self): + pass diff --git a/sendgrid/helpers/inbound/README.md b/sendgrid/helpers/inbound/README.md index 93d0817b6..79e5b4544 100644 --- a/sendgrid/helpers/inbound/README.md +++ b/sendgrid/helpers/inbound/README.md @@ -36,7 +36,7 @@ pip install -r requirements.txt python sendgrid/helpers/inbound/send.py ./sendgrid/helpers/inbound/sample_data/default_data.txt ``` -More sample data can be found [here](https://github.com/sendgrid/sendgrid-python/tree/master/sendgrid/helpers/inbound/sample_data). +More sample data can be found [here](sample_data). View the results in the first terminal. @@ -71,7 +71,7 @@ Next, send an email to [anything]@inbound.yourdomain.com, then look at the termi Get a [Heroku](https://www.heroku.com) account. -[](https://heroku.com/deploy?template=https://github.com/sendgrid/sendgrid-python/tree/master) +[](https://heroku.com/deploy?template=https://github.com/sendgrid/sendgrid-python/tree/main) [Setup your MX records.](https://sendgrid.com/docs/Classroom/Basics/Inbound_Parse_Webhook/setting_up_the_inbound_parse_webhook.html#-Setup) Depending on your domain name host, you may need to wait up to 48 hours for the settings to propagate. @@ -100,7 +100,7 @@ heroku git:remote -a [name-of-your-app] ---make changes--- git add . git commit -m "update configuration" -git push heroku master +git push heroku main ``` @@ -127,12 +127,12 @@ This module is used to send sample test data. It is useful for testing and devel Tests are located in the root of this project in the /test folder: -- [test_config.py](https://github.com/sendgrid/sendgrid-python/blob/master/test/test_config.py) -- [test_parse.py](https://github.com/sendgrid/sendgrid-python/blob/master/test/test_parse.py) +- [test_config.py](../../../test/test_config.py) +- [test_parse.py](../../../test/test_parse.py) -Learn about testing this code [here](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md#testing). +Learn about testing this code [here](../../../CONTRIBUTING.md#testing). # Contributing -If you would like to contribute to this project, please see our [contributing guide](https://github.com/sendgrid/sendgrid-python/blob/master/CONTRIBUTING.md). Thanks! +If you would like to contribute to this project, please see our [contributing guide](../../../CONTRIBUTING.md). Thanks! diff --git a/sendgrid/helpers/inbound/config.py b/sendgrid/helpers/inbound/config.py index 32bec0793..06ca683cb 100644 --- a/sendgrid/helpers/inbound/config.py +++ b/sendgrid/helpers/inbound/config.py @@ -16,7 +16,7 @@ def __init__(self, **opts): 'path', os.path.abspath(os.path.dirname(__file__)) ) with open('{0}/config.yml'.format(self.path)) as stream: - config = yaml.load(stream) + config = yaml.load(stream, Loader=yaml.FullLoader) self._debug_mode = config['debug_mode'] self._endpoint = config['endpoint'] self._host = config['host'] diff --git a/sendgrid/helpers/inbound/sample_data/default_data.txt b/sendgrid/helpers/inbound/sample_data/default_data.txt index cdf52d68b..7c3ce6be2 100644 --- a/sendgrid/helpers/inbound/sample_data/default_data.txt +++ b/sendgrid/helpers/inbound/sample_data/default_data.txt @@ -20,7 +20,7 @@ inbound@inbound.example.com --xYzZY Content-Disposition: form-data; name="html" -
Hello SendGrid! +Hello Twilio SendGrid! --xYzZY Content-Disposition: form-data; name="from" @@ -29,7 +29,7 @@ Example User