From 88ddc58b5c036b1cbd9befa5c8d2856c1512a1a0 Mon Sep 17 00:00:00 2001 From: Xeon Zolt Date: Fri, 5 Oct 2018 23:04:02 +0530 Subject: [PATCH 1/3] fixed changes suggested by grammerly --- CHANGELOG.md | 10 +- CODE_OF_CONDUCT.md | 32 +- CONTRIBUTING.md | 14 +- TROUBLESHOOTING.md | 4 +- USAGE.md | 4623 ++++++++++++++++++++++++++- docker-test/README.md | 2 +- docker/USAGE.md | 2 +- proposals/mail-helper-refactor.md | 2 +- sendgrid/helpers/inbound/README.md | 2 +- use_cases/asynchronous_mail_send.md | 2 +- use_cases/aws.md | 24 +- use_cases/django.md | 8 +- use_cases/flask_heroku.md | 2 +- 13 files changed, 4674 insertions(+), 53 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dd2334ba4..78b7fa26f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,7 +48,7 @@ All notable changes to this project will be documented in this file. - [PR #365](https://github.com/sendgrid/sendgrid-python/pull/365): Write tutorial to deploy simple Django app on Heroku. Big thanks to [Kan Ouivirach](https://github.com/zkan) for the PR! - [PR #526](https://github.com/sendgrid/sendgrid-python/pull/526): Include code reviews section. Big thanks to [Jared Scott](https://github.com/jlax47) for the PR! - [PR #414](https://github.com/sendgrid/sendgrid-python/pull/414): Provide utf-8 as encoding explicitly when opening text files. Big thanks to [Ruslan Shestopalyuk](https://github.com/rshest) for the PR! -- [PR #537](https://github.com/sendgrid/sendgrid-python/pull/537): Add unittesting support to .codeclimate.yml. Big thanks to [Prashu Chaudhary](https://github.com/prashuchaudhary) for the PR! +- [PR #537](https://github.com/sendgrid/sendgrid-python/pull/537): Add unit testing support to .codeclimate.yml. Big thanks to [Prashu Chaudhary](https://github.com/prashuchaudhary) for the PR! - [PR #554](https://github.com/sendgrid/sendgrid-python/pull/554): Ensure params are applied independently. Big thanks to [Nino Milenovic](https://github.com/rubyengineer) for the PR! - [PR #557](https://github.com/sendgrid/sendgrid-python/pull/557): Client cleanup. Big thanks to [Slam](https://github.com/3lnc) for the PR! - [PR #569](https://github.com/sendgrid/sendgrid-python/pull/569): Make Mail helper parameters truly optional. Big thanks to [Ian Beck](https://github.com/onecrayon) for the PR! @@ -58,13 +58,13 @@ All notable changes to this project will be documented in this file. - [PR #421](https://github.com/sendgrid/sendgrid-python/pull/421): Typos. Big thanks to [Abhishek Bhatt](https://github.com/ab-bh) for the PR! - [PR #432](https://github.com/sendgrid/sendgrid-python/pull/432): Typos. Big thanks to [Gaurav Arora](https://github.com/gaurav61) for the PR! - [PR #431](https://github.com/sendgrid/sendgrid-python/pull/431): Typos. Big thanks to [Gaurav Arora](https://github.com/gaurav61) for the PR! -- [PR #430](https://github.com/sendgrid/sendgrid-python/pull/430): Attempt to sync before executing shell command. Big thanks to [Aditya Narayan](https://github.com/aditnryn) for the PR! +- [PR #430](https://github.com/sendgrid/sendgrid-python/pull/430): Attempt to sync before executing the shell command. Big thanks to [Aditya Narayan](https://github.com/aditnryn) for the PR! - [PR #429](https://github.com/sendgrid/sendgrid-python/pull/429): Typos. Big thanks to [daluntw](https://github.com/daluntw) for the PR! - [PR #492](https://github.com/sendgrid/sendgrid-python/pull/492): -Updated date-range in LICENSE file. Big thanks to [Dhruv Srivastava](https://github.com/dhruvhacks) for the PR! +Updated date-range in the LICENSE file. Big thanks to [Dhruv Srivastava](https://github.com/dhruvhacks) for the PR! - [PR #482](https://github.com/sendgrid/sendgrid-python/pull/482): Typos. Big thanks to [Karan Samani](https://github.com/Kimi450) for the PR! - [PR #504](https://github.com/sendgrid/sendgrid-python/pull/504): Fix .codeclimate.yml. Big thanks to [Matt Bernier](https://github.com/mbernier) for the PR! -- [PR #505](https://github.com/sendgrid/sendgrid-python/pull/505): Remove unnecessary github PR templates. Big thanks to [Alex](https://github.com/pushkyn) for the PR! +- [PR #505](https://github.com/sendgrid/sendgrid-python/pull/505): Remove unnecessary GitHub PR templates. Big thanks to [Alex](https://github.com/pushkyn) for the PR! - [PR #494](https://github.com/sendgrid/sendgrid-python/pull/494): Remove unused import in register.py. Big thanks to [Alexis Rivera De La Torre](https://github.com/gardlt) for the PR! - [PR #469](https://github.com/sendgrid/sendgrid-python/pull/469): Removed the trailing white spaces. Big thanks to [Siddaram Halli](https://github.com/SidduH) for the PR! @@ -72,7 +72,7 @@ Removed the trailing white spaces. Big thanks to [Siddaram Halli](https://github - [PR #508](https://github.com/sendgrid/sendgrid-python/pull/508): Typos. Big thanks to [Saksham Gupta](https://github.com/shucon) for the PR! - [PR #353](https://github.com/sendgrid/sendgrid-python/pull/353): Typos. Big thanks to [Yothin M](https://github.com/yothinix) for the PR! - [PR #564](https://github.com/sendgrid/sendgrid-python/pull/564): Typos. Big thanks to [Chao](https://github.com/chaoranxie) for the PR! -- [PR #424](https://github.com/sendgrid/sendgrid-python/pull/424): Updating version 2.7.8 to 2.7.11 to match version in pyenv install instruction. Big thanks to [Krista LaFentres](https://github.com/lafentres) for the PR! +- [PR #424](https://github.com/sendgrid/sendgrid-python/pull/424): Updating version 2.7.8 to 2.7.11 to match the version in pyenv install instruction. Big thanks to [Krista LaFentres](https://github.com/lafentres) for the PR! - [PR #454](https://github.com/sendgrid/sendgrid-python/pull/454): Requests to send mail with both plain text and HTML content fail if the HTML content is specified first. Big thanks to [Ryan D'souza](https://github.com/dsouzarc) for the PR! - [PR #466](https://github.com/sendgrid/sendgrid-python/pull/466): Fixed PEP8 issues. Big thanks to [Piotr Szwarc](https://github.com/blackpioter) for the PR! - [PR #522](https://github.com/sendgrid/sendgrid-python/pull/522): Typos. Big thanks to [Abhishek J](https://github.com/slashstar) for the PR! diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 39ed18bf7..670a82f62 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,41 +1,41 @@ # SendGrid Community Code of Conduct - + The SendGrid open source community is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences successes and continued growth. When you're working with members of the community, we encourage you to follow these guidelines, which help steer our interactions and strive to maintain a positive, successful and growing community. - + ### Be Open Members of the community are open to collaboration, whether it's on pull requests, code reviews, approvals, issues or otherwise. We're receptive to constructive comments and criticism, as the experiences and skill sets of all members contribute to the whole of our efforts. We're accepting of all who wish to take part in our activities, fostering an environment where anyone can participate, and everyone can make a difference. - + ### Be Considerate Members of the community are considerate of their peers, which include other contributors and users of SendGrid. We're thoughtful when addressing the efforts of others, keeping in mind that often the labor was completed with the intent of the good of the community. We're attentive in our communications, whether in person or online, and we're tactful when approaching differing views. - + ### Be Respectful - Members of the community are respectful. We're respectful of others, their positions, their skills, their commitments and their efforts. We're respectful of the volunteer efforts that permeate the SendGrid community. We're respectful of the processes outlined in the community, and we work within them. When we disagree, we are courteous in raising our issues. Overall, we're good to each other. We contribute to this community not because we have to, but because we want to. If we remember that, these guidelines will come naturally. - + Members of the community are respectful. We're respectful of others, their positions, their skills, their commitments ,and their efforts. We're respectful of the volunteer efforts that permeate the SendGrid community. We're respectful of the processes outlined in the community, and we work within them. When we disagree, we are courteous in raising our issues. Overall, we're good with each other. We contribute to this community not because we have to, but because we want to. If we remember that, these guidelines will come naturally. + ## Additional Guidance - + ### Disclose Potential Conflicts of Interest Community discussions often involve interested parties. We expect participants to be aware when they are conflicted due to employment or other projects they are involved in and disclose those interests to other project members. When in doubt, over-disclose. Perceived conflicts of interest are important to address so that the community’s decisions are credible even when unpopular, difficult or favorable to the interests of one group over another. - + ### Interpretation This Code is not exhaustive or complete. It is not a rulebook; it serves to distill our common understanding of a collaborative, shared environment and goals. We expect it to be followed in spirit as much as in the letter. When in doubt, try to abide by [SendGrid’s cultural values](https://sendgrid.com/blog/employee-engagement-the-4h-way) defined by our “4H’s”: Happy, Hungry, Humble and Honest. - + ### Enforcement Most members of the SendGrid community always comply with this Code, not because of the existence of this Code, but because they have long experience participating in open source communities where the conduct described above is normal and expected. However, failure to observe this Code may be grounds for suspension, reporting the user for abuse or changing permissions for outside contributors. - + ## If you have concerns about someone’s conduct **Initiate Direct Contact** - It is always appropriate to email a community member (if contact information is available), mention that you think their behavior was out of line, and (if necessary) point them to this Code. - + **Discuss Publicly** - Discussing publicly is always acceptable. Note, though, that approaching the person directly may be better, as it tends to make them less defensive, and it respects the time of other community members, so you probably want to try direct contact first. - + **Contact the Moderators** - You can reach the SendGrid moderators by emailing dx@sendgrid.com. - + ## Submission to SendGrid Repositories Finally, just a reminder, changes to the SendGrid repositories will only be accepted upon completion of the [SendGrid Contributor Agreement](https://cla.sendgrid.com). - + ## Attribution - + SendGrid thanks the following, on which it draws for content and inspiration: - + [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/) [Open Source Initiative General Code of Conduct](https://opensource.org/codeofconduct) [Apache Code of Conduct](https://www.apache.org/foundation/policies/conduct.html) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a875bf9c1..90f8a1f42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,14 +12,14 @@ Hello! Thank you for choosing to help contribute to one of the SendGrid open sou - [Code Reviews](#code-reviews) -We use [Milestones](https://github.com/sendgrid/sendgrid-python/milestones) to help define current roadmaps, please feel free to grab an issue from the current milestone. Please indicate that you have begun work on it to avoid collisions. Once a PR is made, community reviews, comments, suggestions and additional PRs are welcomed and encouraged. +We use [Milestones](https://github.com/sendgrid/sendgrid-python/milestones) to help define current roadmaps, please feel free to grab an issue from the current milestone. Please indicate that you have begun work on it to avoid collisions. Once a PR is made, community reviews, comments, suggestions, and additional PRs are welcomed and encouraged. ## CLAs and CCLAs Before you get started, SendGrid requires that a SendGrid Contributor License Agreement (CLA) be filled out by every contributor to a SendGrid open source project. -Our goal with the CLA is to clarify the rights of our contributors and reduce other risks arising from inappropriate contributions. The CLA also clarifies the rights SendGrid holds in each contribution and helps to avoid misunderstandings over what rights each contributor is required to grant to SendGrid when making a contribution. In this way the CLA encourages broad participation by our open source community and helps us build strong open source projects, free from any individual contributor withholding or revoking rights to any contribution. +Our goal with the CLA is to clarify the rights of our contributors and reduce other risks arising from inappropriate contributions. The CLA also clarifies the rights SendGrid holds in each contribution and helps to avoid misunderstandings over what rights each contributor is required to grant to SendGrid when making a contribution. In this way, the CLA encourages broad participation by our open source community and helps us build strong open source projects, free from any individual contributor withholding or revoking rights to any contribution. SendGrid does not merge a pull request made against a SendGrid open source project until that pull request is associated with a signed CLA. Copies of the CLA are available [here](https://gist.github.com/SendGridDX/98b42c0a5d500058357b80278fde3be8#file-sendgrid_cla). @@ -47,7 +47,7 @@ A software bug is a demonstrable issue in the code base. In order for us to diag Before you decide to create a new issue, please try the following: 1. Check the GitHub issues tab if the identified issue has already been reported, if so, please add a +1 to the existing post. -2. Update to the latest version of this code and check if issue has already been fixed +2. Update to the latest version of this code and check if the issue has already been fixed 3. Copy and fill in the Bug Report Template we have provided below ### Please use our Bug Report Template @@ -107,7 +107,7 @@ Working examples that demonstrate usage. **/tests** -Currently we have unit and profiling tests. +Currently, we have unit and profiling tests. **/sendgrid** @@ -206,14 +206,14 @@ Please run your code through: git pull upstream ``` -3. Create a new topic branch (off the main project development branch) to +3. Create a new topic branch (of the main project development branch) to contain your feature, change, or fix: ```bash git checkout -b ``` -4. Commit your changes in logical chunks. Please adhere to these [git commit +4. Commit your changes in logical chunks. Please adhere to these [git commits message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) or your code is unlikely to be merged into the main project. Use Git's [interactive rebase](https://help.github.com/articles/interactive-rebase) @@ -242,4 +242,4 @@ If you have any additional questions, please feel free to [email](mailto:dx@send ## Code Reviews -If you can, please look at open PRs and review them. Give feedback and help us merge these PRs much faster! If you don't know how, GitHub has some great [information on how to review a Pull Request](https://help.github.com/articles/about-pull-request-reviews/). +If you can, please look at open PRs and review them. Give feedback and help us merge these PRs much faster! If you don't know how GitHub has some great [information on how to review a Pull Request](https://help.github.com/articles/about-pull-request-reviews/). diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 1298ab7d1..a33919a26 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -27,7 +27,7 @@ becomes `apikey='SENDGRID_API_KEY'` -In the first case SENDGRID_API_KEY is in reference to the name of the environment variable, while the second case references the actual SendGrid API Key. +In the first case, SENDGRID_API_KEY is in reference to the name of the environment variable, while the second case references the actual SendGrid API Key. ## Error Messages @@ -95,7 +95,7 @@ If you are using a [requirements file](https://pip.readthedocs.io/en/1.1/require ## Versioning Convention -We follow the MAJOR.MINOR.PATCH versioning scheme as described by [SemVer.org](http://semver.org). Therefore, we recommend that you always pin (or vendor) the particular version you are working with to your code and never auto-update to the latest version. Especially when there is a MAJOR point release, since that is guaranteed to be a breaking change. Changes are documented in the [CHANGELOG](https://github.com/sendgrid/sendgrid-python/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-python/releases) section. +We follow the MAJOR.MINOR.PATCH versioning scheme as described by [SemVer.org](http://semver.org). Therefore, we recommend that you always pin (or vendor) the particular version you are working with your code and never auto-update to the latest version. Especially when there is a MAJOR point release since that is guaranteed to be a breaking change. Changes are documented in the [CHANGELOG](https://github.com/sendgrid/sendgrid-python/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-python/releases) section. ## Viewing the Request Body diff --git a/USAGE.md b/USAGE.md index 09b78609a..ea2beae39 100644 --- a/USAGE.md +++ b/USAGE.md @@ -70,7 +70,4628 @@ IP Access Management allows you to control which IP addresses can be used to acc For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). -### POST /access_settings/whitelist +This documentation is based on our OAI specification. + +INITIALIZATION + + +import sendgrid +import os + + +sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) +Table of Contents + +ACCESS SETTINGS + +ALERTS + +API KEYS + +ASM + +BROWSERS + +CAMPAIGNS + +CATEGORIES + +CLIENTS + +CONTACTDB + +DEVICES + +GEO + +IPS + +MAIL + +MAIL SETTINGS + +MAILBOX PROVIDERS + +PARTNER SETTINGS + +SCOPES + +SENDERS + +STATS + +SUBUSERS + +SUPPRESSION + +TEMPLATES + +TRACKING SETTINGS + +USER + +WHITELABEL + + + +ACCESS SETTINGS + +Retrieve all recent access attempts + +This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API. + +IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + +For more information, please see our User Guide. + +GET /access_settings/activity + + +params = {'limit': 1} +response = sg.client.access_settings.activity.get(query_params=params) +print response.status_code +print response.body +print response.headers +Add one or more IPs to the whitelist + +This endpoint allows you to add one or more IP addresses to your IP whitelist. + +When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once. + +IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + +For more information, please see our User Guide. + +POST /access_settings/whitelist + + +data = { + "ips": [ +​ { +​ "ip": "192.168.1.1" +​ }, +​ { +​ "ip": "192.*.*.*" +​ }, +​ { +​ "ip": "192.168.1.3/32" +​ } + ] +} +response = sg.client.access_settings.whitelist.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a list of currently whitelisted IPs + +This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted. + +IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + +For more information, please see our User Guide. + +GET /access_settings/whitelist + + +response = sg.client.access_settings.whitelist.get() +print response.status_code +print response.body +print response.headers +Remove one or more IPs from the whitelist + +This endpoint allows you to remove one or more IPs from your IP whitelist. + +You can remove one IP at a time, or you can remove multiple IP addresses. + +IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + +For more information, please see our User Guide. + +DELETE /access_settings/whitelist + + +data = { + "ids": [ +​ 1, +​ 2, +​ 3 + ] +} +response = sg.client.access_settings.whitelist.delete(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a specific whitelisted IP + +This endpoint allows you to retrieve a specific IP address that has been whitelisted. + +You must include the ID for the specific IP address you want to retrieve in your call. + +IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + +For more information, please see our User Guide. + +GET /access_settings/whitelist/{rule_id} + + +rule_id = "test_url_param" +response = sg.client.access_settings.whitelist._(rule_id).get() +print response.status_code +print response.body +print response.headers +Remove a specific IP from the whitelist + +This endpoint allows you to remove a specific IP address from your IP whitelist. + +When removing a specific IP address from your whitelist, you must include the ID in your call. + +IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. + +For more information, please see our User Guide. + +DELETE /access_settings/whitelist/{rule_id} + + +rule_id = "test_url_param" +response = sg.client.access_settings.whitelist._(rule_id).delete() +print response.status_code +print response.body +print response.headers + + +ALERTS + +Create a new Alert + +This endpoint allows you to create a new alert. + +Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + +Usage alerts allow you to set the threshold at which an alert will be sent. + +Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + +For more information about alerts, please see our User Guide. + +POST /alerts + + +data = { + "email_to": "example@example.com", + "frequency": "daily", + "type": "stats_notification" +} +response = sg.client.alerts.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all alerts + +GET /alerts + + +response = sg.client.alerts.get() +print response.status_code +print response.body +print response.headers +Update an alert + +This endpoint allows you to update an alert. + +Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + +Usage alerts allow you to set the threshold at which an alert will be sent. + +Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + +For more information about alerts, please see our User Guide. + +PATCH /alerts/{alert_id} + + +data = { + "email_to": "example@example.com" +} +alert_id = "test_url_param" +response = sg.client.alerts._(alert_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a specific alert + +This endpoint allows you to retrieve a specific alert. + +Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + +Usage alerts allow you to set the threshold at which an alert will be sent. + +Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + +For more information about alerts, please see our User Guide. + +GET /alerts/{alert_id} + + +alert_id = "test_url_param" +response = sg.client.alerts._(alert_id).get() +print response.status_code +print response.body +print response.headers +Delete an alert + +This endpoint allows you to delete an alert. + +Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. + +Usage alerts allow you to set the threshold at which an alert will be sent. + +Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". + +For more information about alerts, please see our User Guide. + +DELETE /alerts/{alert_id} + + +alert_id = "test_url_param" +response = sg.client.alerts._(alert_id).delete() +print response.status_code +print response.body +print response.headers + + +API KEYS + +Create API keys + +This endpoint allows you to create a new random API Key for the user. + +A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. + +There is a limit of 100 API Keys on your account. + +The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. + +See the API Key Permissions List for a list of all available scopes. + +POST /api_keys + + +data = { + "name": "My API Key", + "sample": "data", + "scopes": [ +​ "mail.send", +​ "alerts.create", +​ "alerts.read" + ] +} +response = sg.client.api_keys.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all API Keys belonging to the authenticated user + +This endpoint allows you to retrieve all API Keys that belong to the authenticated user. + +The API Keys feature allows customers to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. + +GET /api_keys + + +params = {'limit': 1} +response = sg.client.api_keys.get(query_params=params) +print response.status_code +print response.body +print response.headers +Update the name & scopes of an API Key + +This endpoint allows you to update the name and scopes of a given API key. + +A JSON request body with a "name" property is required. +Most provide the list of all the scopes an api key should have. + +The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. + +PUT /api_keys/{api_key_id} + + +data = { + "name": "A New Hope", + "scopes": [ +​ "user.profile.read", +​ "user.profile.update" + ] +} +api_key_id = "test_url_param" +response = sg.client.api_keys._(api_key_id).put(request_body=data) +print response.status_code +print response.body +print response.headers +Update API keys + +This endpoint allows you to update the name of an existing API Key. + +A JSON request body with a "name" property is required. + +The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. + +URI Parameters + +URI PARAMETER TYPE REQUIRED? DESCRIPTION +api_key_id string required The ID of the API Key you are updating. +PATCH /api_keys/{api_key_id} + + +data = { + "name": "A New Hope" +} +api_key_id = "test_url_param" +response = sg.client.api_keys._(api_key_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve an existing API Key + +This endpoint allows you to retrieve a single API key. + +If the API Key ID does not exist an HTTP 404 will be returned. + +GET /api_keys/{api_key_id} + + +api_key_id = "test_url_param" +response = sg.client.api_keys._(api_key_id).get() +print response.status_code +print response.body +print response.headers +Delete API keys + +This endpoint allows you to revoke an existing API Key. + +Authentications using this API Key will fail after this request is made, with some small propagation delay.If the API Key ID does not exist an HTTP 404 will be returned. + +The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. + +URI Parameters + +URI PARAMETER TYPE REQUIRED? DESCRIPTION +api_key_id string required The ID of the API Key you are deleting. +DELETE /api_keys/{api_key_id} + + +api_key_id = "test_url_param" +response = sg.client.api_keys._(api_key_id).delete() +print response.status_code +print response.body +print response.headers + + +ASM + +Create a new suppression group + +This endpoint allows you to create a new suppression group. + +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + +The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + +Each user can create up to 25 different suppression groups. + +POST /asm/groups + + +data = { + "description": "Suggestions for products our users might like.", + "is_default": True, + "name": "Product Suggestions" +} +response = sg.client.asm.groups.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve information about multiple suppression groups + +This endpoint allows you to retrieve information about multiple suppression groups. + +This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append &id= followed by the group ID. + +Suppressions are a list of email addresses that will not receive content sent under a given group. + +Suppression groups, or unsubscribe groups, allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue receiving your transactional email without having to receive your marketing content. + +GET /asm/groups + + +params = {'id': 1} +response = sg.client.asm.groups.get(query_params=params) +print response.status_code +print response.body +print response.headers +Update a suppression group. + +This endpoint allows you to update or change a suppression group. + +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + +The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + +Each user can create up to 25 different suppression groups. + +PATCH /asm/groups/{group_id} + + +data = { + "description": "Suggestions for items our users might like.", + "id": 103, + "name": "Item Suggestions" +} +group_id = "test_url_param" +response = sg.client.asm.groups._(group_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Get information on a single suppression group. + +This endpoint allows you to retrieve a single suppression group. + +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + +The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + +Each user can create up to 25 different suppression groups. + +GET /asm/groups/{group_id} + + +group_id = "test_url_param" +response = sg.client.asm.groups._(group_id).get() +print response.status_code +print response.body +print response.headers +Delete a suppression group. + +This endpoint allows you to delete a suppression group. + +You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list. + +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. + +The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. + +Each user can create up to 25 different suppression groups. + +DELETE /asm/groups/{group_id} + + +group_id = "test_url_param" +response = sg.client.asm.groups._(group_id).delete() +print response.status_code +print response.body +print response.headers +Add suppressions to a suppression group + +This endpoint allows you to add email addresses to an unsubscribe group. + +If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list. + +Suppressions are recipient email addresses that are added to unsubscribe groups. Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + +POST /asm/groups/{group_id}/suppressions + + +data = { + "recipient_emails": [ +​ "test1@example.com", +​ "test2@example.com" + ] +} +group_id = "test_url_param" +response = sg.client.asm.groups._(group_id).suppressions.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all suppressions for a suppression group + +This endpoint allows you to retrieve all suppressed email addresses belonging to the given group. + +Suppressions are recipient email addresses that are added to unsubscribe groups. Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + +GET /asm/groups/{group_id}/suppressions + + +group_id = "test_url_param" +response = sg.client.asm.groups._(group_id).suppressions.get() +print response.status_code +print response.body +print response.headers +Search for suppressions within a group + +This endpoint allows you to search a suppression group for multiple suppressions. + +When given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group. + +Suppressions are a list of email addresses that will not receive content sent under a given group. + +POST /asm/groups/{group_id}/suppressions/search + + +data = { + "recipient_emails": [ +​ "exists1@example.com", +​ "exists2@example.com", +​ "doesnotexists@example.com" + ] +} +group_id = "test_url_param" +response = sg.client.asm.groups._(group_id).suppressions.search.post(request_body=data) +print response.status_code +print response.body +print response.headers +Delete a suppression from a suppression group + +This endpoint allows you to remove a suppressed email address from the given suppression group. + +Suppressions are recipient email addresses that are added to unsubscribe groups. Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. + +DELETE /asm/groups/{group_id}/suppressions/{email} + + +group_id = "test_url_param" +email = "test_url_param" +response = sg.client.asm.groups._(group_id).suppressions._(email).delete() +print response.status_code +print response.body +print response.headers +Retrieve all suppressions + +This endpoint allows you to retrieve a list of all suppressions. + +Suppressions are a list of email addresses that will not receive content sent under a given group. + +GET /asm/suppressions + + +response = sg.client.asm.suppressions.get() +print response.status_code +print response.body +print response.headers +Add recipient addresses to the global suppression group. + +This endpoint allows you to add one or more email addresses to the global suppressions group. + +A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. + +POST /asm/suppressions/global + + +data = { + "recipient_emails": [ +​ "test1@example.com", +​ "test2@example.com" + ] +} +response = sg.client.asm.suppressions._("global").post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a Global Suppression + +This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppressed. + +If the email address you include in the URL path parameter {email} is already globally suppressed, the response will include that email address. If the address you enter for {email} is not globally suppressed, an empty JSON object {} will be returned. + +A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. + +GET /asm/suppressions/global/{email} + + +email = "test_url_param" +response = sg.client.asm.suppressions._("global")._(email).get() +print response.status_code +print response.body +print response.headers +Delete a Global Suppression + +This endpoint allows you to remove an email address from the global suppressions group. + +A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. + +DELETE /asm/suppressions/global/{email} + + +email = "test_url_param" +response = sg.client.asm.suppressions._("global")._(email).delete() +print response.status_code +print response.body +print response.headers +Retrieve all suppression groups for an email address + +This endpoint returns the list of all groups that the given email address has been unsubscribed from. + +Suppressions are a list of email addresses that will not receive content sent under a given group. + +GET /asm/suppressions/{email} + + +email = "test_url_param" +response = sg.client.asm.suppressions._(email).get() +print response.status_code +print response.body +print response.headers + + +BROWSERS + +Retrieve email statistics by browser. + +This endpoint allows you to retrieve your email statistics segmented by browser type. + +We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. + +Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. + +GET /browsers/stats + + +params = {'end_date': '2016-04-01', 'aggregated_by': 'day', 'browsers': 'test_string', 'limit': 'test_string', 'offset': 'test_string', 'start_date': '2016-01-01'} +response = sg.client.browsers.stats.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +CAMPAIGNS + +Create a Campaign + +This endpoint allows you to create a campaign. + +Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + +Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. + +For more information: + +User Guide > Marketing Campaigns + +POST /campaigns + + +data = { + "categories": [ +​ "spring line" + ], + "custom_unsubscribe_url": "", + "html_content": "

Check out our spring line!

", + "ip_pool": "marketing", + "list_ids": [ +​ 110, +​ 124 + ], + "plain_content": "Check out our spring line!", + "segment_ids": [ +​ 110 + ], + "sender_id": 124451, + "subject": "New Products for Spring!", + "suppression_group_id": 42, + "title": "March Newsletter" +} +response = sg.client.campaigns.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all Campaigns + +This endpoint allows you to retrieve a list of all of your campaigns. + +Returns campaigns in reverse order they were created (newest first). + +Returns an empty array if no campaigns exist. + +For more information: + +User Guide > Marketing Campaigns + +GET /campaigns + + +params = {'limit': 10, 'offset': 0} +response = sg.client.campaigns.get(query_params=params) +print response.status_code +print response.body +print response.headers +Update a Campaign + +Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. + +For more information: + +User Guide > Marketing Campaigns + +PATCH /campaigns/{campaign_id} + + +data = { + "categories": [ +​ "summer line" + ], + "html_content": "

Check out our summer line!

", + "plain_content": "Check out our summer line!", + "subject": "New Products for Summer!", + "title": "May Newsletter" +} +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a single campaign + +This endpoint allows you to retrieve a specific campaign. + +Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + +For more information: + +User Guide > Marketing Campaigns + +GET /campaigns/{campaign_id} + + +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).get() +print response.status_code +print response.body +print response.headers +Delete a Campaign + +This endpoint allows you to delete a specific campaign. + +Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. + +For more information: + +User Guide > Marketing Campaigns + +DELETE /campaigns/{campaign_id} + + +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).delete() +print response.status_code +print response.body +print response.headers +Update a Scheduled Campaign + +This endpoint allows to you change the scheduled time and date for a campaign to be sent. + +For more information: + +User Guide > Marketing Campaigns + +PATCH /campaigns/{campaign_id}/schedules + + +data = { + "send_at": 1489451436 +} +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).schedules.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Schedule a Campaign + +This endpoint allows you to schedule a specific date and time for your campaign to be sent. + +For more information: + +User Guide > Marketing Campaigns + +POST /campaigns/{campaign_id}/schedules + + +data = { + "send_at": 1489771528 +} +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).schedules.post(request_body=data) +print response.status_code +print response.body +print response.headers +View Scheduled Time of a Campaign + +This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent. + +For more information: + +User Guide > Marketing Campaigns + +GET /campaigns/{campaign_id}/schedules + + +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).schedules.get() +print response.status_code +print response.body +print response.headers +Unschedule a Scheduled Campaign + +This endpoint allows you to unschedule a campaign that has already been scheduled to be sent. + +A successful unschedule will return a 204. +If the specified campaign is in the process of being sent, the only option is to cancel (a different method). + +For more information: + +User Guide > Marketing Campaigns + +DELETE /campaigns/{campaign_id}/schedules + + +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).schedules.delete() +print response.status_code +print response.body +print response.headers +Send a Campaign + +This endpoint allows you to immediately send a campaign at the time you make the API call. + +Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed. + +For more information: + +User Guide > Marketing Campaigns + +POST /campaigns/{campaign_id}/schedules/now + + +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).schedules.now.post() +print response.status_code +print response.body +print response.headers +Send a Test Campaign + +This endpoint allows you to send a test campaign. + +To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] + +For more information: + +User Guide > Marketing Campaigns + +POST /campaigns/{campaign_id}/schedules/test + + +data = { + "to": "your.email@example.com" +} +campaign_id = "test_url_param" +response = sg.client.campaigns._(campaign_id).schedules.test.post(request_body=data) +print response.status_code +print response.body +print response.headers + + +CATEGORIES + +Retrieve all categories + +This endpoint allows you to retrieve a list of all of your categories. + +Categories can help organize your email analytics by enabling you to tag emails by type or broad topic. You can define your own custom categories. For more information, please see our User Guide. + +GET /categories + + +params = {'category': 'test_string', 'limit': 1, 'offset': 1} +response = sg.client.categories.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve Email Statistics for Categories + +This endpoint allows you to retrieve all of your email statistics for each of your categories. + +If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. + +Categories allow you to group your emails together according to broad topics that you define. For more information, please see our User Guide. + +GET /categories/stats + + +params = {'end_date': '2016-04-01', 'aggregated_by': 'day', 'limit': 1, 'offset': 1, 'start_date': '2016-01-01', 'categories': 'test_string'} +response = sg.client.categories.stats.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?] + +This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range. + +If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. + +Categories allow you to group your emails together according to broad topics that you define. For more information, please see our User Guide. + +GET /categories/stats/sums + + +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.categories.stats.sums.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +CLIENTS + +Retrieve email statistics by client type. + +This endpoint allows you to retrieve your email statistics segmented by client type. + +We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. + +Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. + +GET /clients/stats + + +params = {'aggregated_by': 'day', 'start_date': '2016-01-01', 'end_date': '2016-04-01'} +response = sg.client.clients.stats.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve stats by a specific client type. + +This endpoint allows you to retrieve your email statistics segmented by a specific client type. + +We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. + +Available Client Types + +phone + +tablet + +webmail + +desktop + +Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. + +GET /clients/{client_type}/stats + + +params = {'aggregated_by': 'day', 'start_date': '2016-01-01', 'end_date': '2016-04-01'} +client_type = "test_url_param" +response = sg.client.clients._(client_type).stats.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +CONTACTDB + +Create a Custom Field + +This endpoint allows you to create a custom field. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +POST /contactdb/custom_fields + + +data = { + "name": "pet", + "type": "text" +} +response = sg.client.contactdb.custom_fields.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all custom fields + +This endpoint allows you to retrieve all custom fields. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +GET /contactdb/custom_fields + + +response = sg.client.contactdb.custom_fields.get() +print response.status_code +print response.body +print response.headers +Retrieve a Custom Field + +This endpoint allows you to retrieve a custom field by ID. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +GET /contactdb/custom_fields/{custom_field_id} + + +custom_field_id = "test_url_param" +response = sg.client.contactdb.custom_fields._(custom_field_id).get() +print response.status_code +print response.body +print response.headers +Delete a Custom Field + +This endpoint allows you to delete a custom field by ID. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +DELETE /contactdb/custom_fields/{custom_field_id} + + +custom_field_id = "test_url_param" +response = sg.client.contactdb.custom_fields._(custom_field_id).delete() +print response.status_code +print response.body +print response.headers +Create a List + +This endpoint allows you to create a list for your recipients. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +POST /contactdb/lists + + +data = { + "name": "your list name" +} +response = sg.client.contactdb.lists.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all lists + +This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +GET /contactdb/lists + + +response = sg.client.contactdb.lists.get() +print response.status_code +print response.body +print response.headers +Delete Multiple lists + +This endpoint allows you to delete multiple recipient lists. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +DELETE /contactdb/lists + + +data = [ + 1, + 2, + 3, + 4 +] +response = sg.client.contactdb.lists.delete(request_body=data) +print response.status_code +print response.body +print response.headers +Update a List + +This endpoint allows you to update the name of one of your recipient lists. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +PATCH /contactdb/lists/{list_id} + + +data = { + "name": "newlistname" +} +params = {'list_id': 1} +list_id = "test_url_param" +response = sg.client.contactdb.lists._(list_id).patch(request_body=data, query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve a single list + +This endpoint allows you to retrieve a single recipient list. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +GET /contactdb/lists/{list_id} + + +params = {'list_id': 1} +list_id = "test_url_param" +response = sg.client.contactdb.lists._(list_id).get(query_params=params) +print response.status_code +print response.body +print response.headers +Delete a List + +This endpoint allows you to delete a specific recipient list with the given ID. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +DELETE /contactdb/lists/{list_id} + + +params = {'delete_contacts': 'true'} +list_id = "test_url_param" +response = sg.client.contactdb.lists._(list_id).delete(query_params=params) +print response.status_code +print response.body +print response.headers +Add Multiple Recipients to a List + +This endpoint allows you to add multiple recipients to a list. + +Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +POST /contactdb/lists/{list_id}/recipients + + +data = [ + "recipient_id1", + "recipient_id2" +] +list_id = "test_url_param" +response = sg.client.contactdb.lists._(list_id).recipients.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all recipients on a List + +This endpoint allows you to retrieve all recipients on the list with the given ID. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +GET /contactdb/lists/{list_id}/recipients + + +params = {'page': 1, 'page_size': 1, 'list_id': 1} +list_id = "test_url_param" +response = sg.client.contactdb.lists._(list_id).recipients.get(query_params=params) +print response.status_code +print response.body +print response.headers +Add a Single Recipient to a List + +This endpoint allows you to add a single recipient to a list. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +POST /contactdb/lists/{list_id}/recipients/{recipient_id} + + +list_id = "test_url_param" +recipient_id = "test_url_param" +response = sg.client.contactdb.lists._(list_id).recipients._(recipient_id).post() +print response.status_code +print response.body +print response.headers +Delete a Single Recipient from a Single List + +This endpoint allows you to delete a single recipient from a list. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +DELETE /contactdb/lists/{list_id}/recipients/{recipient_id} + + +params = {'recipient_id': 1, 'list_id': 1} +list_id = "test_url_param" +recipient_id = "test_url_param" +response = sg.client.contactdb.lists._(list_id).recipients._(recipient_id).delete(query_params=params) +print response.status_code +print response.body +print response.headers +Update Recipient + +This endpoint allows you to update one or more recipients. + +The body of an API call to this endpoint must include an array of one or more recipient objects. + +It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +PATCH /contactdb/recipients + + +data = [ + { +​ "email": "jones@example.com", +​ "first_name": "Guy", +​ "last_name": "Jones" + } +] +response = sg.client.contactdb.recipients.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Add recipients + +This endpoint allows you to add a Marketing Campaigns recipient. + +It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +POST /contactdb/recipients + + +data = [ + { +​ "age": 25, +​ "email": "example@example.com", +​ "first_name": "", +​ "last_name": "User" + }, + { +​ "age": 25, +​ "email": "example2@example.com", +​ "first_name": "Example", +​ "last_name": "User" + } +] +response = sg.client.contactdb.recipients.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve recipients + +This endpoint allows you to retrieve all of your Marketing Campaigns recipients. + +Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of +the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +GET /contactdb/recipients + + +params = {'page': 1, 'page_size': 1} +response = sg.client.contactdb.recipients.get(query_params=params) +print response.status_code +print response.body +print response.headers +Delete Recipient + +This endpoint allows you to deletes one or more recipients. + +The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +DELETE /contactdb/recipients + + +data = [ + "recipient_id1", + "recipient_id2" +] +response = sg.client.contactdb.recipients.delete(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve the count of billable recipients + +This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for. + +You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +GET /contactdb/recipients/billable_count + + +response = sg.client.contactdb.recipients.billable_count.get() +print response.status_code +print response.body +print response.headers +Retrieve a Count of Recipients + +This endpoint allows you to retrieve the total number of Marketing Campaigns recipients. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +GET /contactdb/recipients/count + + +response = sg.client.contactdb.recipients.count.get() +print response.status_code +print response.body +print response.headers +Retrieve recipients matching search criteria + +This endpoint allows you to perform a search on all of your Marketing Campaigns recipients. + +field_name: + +is a variable that is substituted for your actual custom field name from your recipient. + +Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) + +If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert +your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to +Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through +Mon, 02 Feb 2015 23:59:59 GMT. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +GET /contactdb/recipients/search + + +params = {'{field_name}': 'test_string'} +response = sg.client.contactdb.recipients.search.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve a single recipient + +This endpoint allows you to retrieve a single recipient by ID from your contact database. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +GET /contactdb/recipients/{recipient_id} + + +recipient_id = "test_url_param" +response = sg.client.contactdb.recipients._(recipient_id).get() +print response.status_code +print response.body +print response.headers +Delete a Recipient + +This endpoint allows you to delete a single recipient with the given ID from your contact database. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +DELETE /contactdb/recipients/{recipient_id} + + +recipient_id = "test_url_param" +response = sg.client.contactdb.recipients._(recipient_id).delete() +print response.status_code +print response.body +print response.headers +Retrieve the lists that a recipient is on + +This endpoint allows you to retrieve the lists that a given recipient belongs to. + +Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +GET /contactdb/recipients/{recipient_id}/lists + + +recipient_id = "test_url_param" +response = sg.client.contactdb.recipients._(recipient_id).lists.get() +print response.status_code +print response.body +print response.headers +Retrieve reserved fields + +This endpoint allows you to list all fields that are reserved and can't be used for custom field names. + +The contactdb is a database of your contacts for SendGrid Marketing Campaigns. + +GET /contactdb/reserved_fields + + +response = sg.client.contactdb.reserved_fields.get() +print response.status_code +print response.body +print response.headers +Create a Segment + +This endpoint allows you to create a segment. + +All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment. + +List Id: + +Send this to segment from an existing list + +Don't send this in order to segment from your entire contactdb. + +Valid operators for create and update depend on the type of the field you are segmenting: + +Dates: "eq", "ne", "lt" (before), "gt" (after) + +Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value) + +Numbers: "eq", "lt", "gt" + +Email Clicks and Opens: "eq" (opened), "ne" (not opened) + +Segment conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either clicks.campaign_identifier or opens.campaign_identifier. The condition value should be a string containing the id of a completed campaign. + +Segments may contain multiple conditions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or". + +The Contacts API helps you manage your Marketing Campaigns recipients. + +For more information about segments in Marketing Campaigns, please see our User Guide. + +POST /contactdb/segments + + +data = { + "conditions": [ +​ { +​ "and_or": "", +​ "field": "last_name", +​ "operator": "eq", +​ "value": "Miller" +​ }, +​ { +​ "and_or": "and", +​ "field": "last_clicked", +​ "operator": "gt", +​ "value": "01/02/2015" +​ }, +​ { +​ "and_or": "or", +​ "field": "clicks.campaign_identifier", +​ "operator": "eq", +​ "value": "513" +​ } + ], + "list_id": 4, + "name": "Last Name Miller" +} +response = sg.client.contactdb.segments.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all segments + +This endpoint allows you to retrieve all of your segments. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +For more information about segments in Marketing Campaigns, please see our User Guide. + +GET /contactdb/segments + + +response = sg.client.contactdb.segments.get() +print response.status_code +print response.body +print response.headers +Update a segment + +This endpoint allows you to update a segment. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +For more information about segments in Marketing Campaigns, please see our User Guide. + +PATCH /contactdb/segments/{segment_id} + + +data = { + "conditions": [ +​ { +​ "and_or": "", +​ "field": "last_name", +​ "operator": "eq", +​ "value": "Miller" +​ } + ], + "list_id": 5, + "name": "The Millers" +} +params = {'segment_id': 'test_string'} +segment_id = "test_url_param" +response = sg.client.contactdb.segments._(segment_id).patch(request_body=data, query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve a segment + +This endpoint allows you to retrieve a single segment with the given ID. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +For more information about segments in Marketing Campaigns, please see our User Guide. + +GET /contactdb/segments/{segment_id} + + +params = {'segment_id': 1} +segment_id = "test_url_param" +response = sg.client.contactdb.segments._(segment_id).get(query_params=params) +print response.status_code +print response.body +print response.headers +Delete a segment + +This endpoint allows you to delete a segment from your recipients database. + +You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +For more information about segments in Marketing Campaigns, please see our User Guide. + +DELETE /contactdb/segments/{segment_id} + + +params = {'delete_contacts': 'true'} +segment_id = "test_url_param" +response = sg.client.contactdb.segments._(segment_id).delete(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve recipients on a segment + +This endpoint allows you to retrieve all of the recipients in a segment with the given ID. + +The Contacts API helps you manage your Marketing Campaigns recipients. + +For more information about segments in Marketing Campaigns, please see our User Guide. + +GET /contactdb/segments/{segment_id}/recipients + + +params = {'page': 1, 'page_size': 1} +segment_id = "test_url_param" +response = sg.client.contactdb.segments._(segment_id).recipients.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +DEVICES + +Retrieve email statistics by device type. + +This endpoint allows you to retrieve your email statistics segmented by the device type. + +We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. + +Available Device Types + +DEVICE DESCRIPTION EXAMPLE +Desktop Email software on desktop computer. I.E., Outlook, Sparrow, or Apple Mail. +Webmail A web-based email client. I.E., Yahoo, Google, AOL, or Outlook.com. +| Phone | A smart phone. | iPhone, Android, Blackberry, etc. +| Tablet | A tablet computer. | iPad, android based tablet, etc. | +| Other | An unrecognized device. | + +Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. + +GET /devices/stats + + +params = {'aggregated_by': 'day', 'limit': 1, 'start_date': '2016-01-01', 'end_date': '2016-04-01', 'offset': 1} +response = sg.client.devices.stats.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +GEO + +Retrieve email statistics by country and state/province. + +This endpoint allows you to retrieve your email statistics segmented by country and state/province. + +We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. + +Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. + +GET /geo/stats + + +params = {'end_date': '2016-04-01', 'country': 'US', 'aggregated_by': 'day', 'limit': 1, 'offset': 1, 'start_date': '2016-01-01'} +response = sg.client.geo.stats.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +IPS + +Retrieve all IP addresses + +This endpoint allows you to retrieve a list of all assigned and unassigned IPs. + +Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. + +A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + +GET /ips + + +params = {'subuser': 'test_string', 'ip': 'test_string', 'limit': 1, 'exclude_whitelabels': 'true', 'offset': 1} +response = sg.client.ips.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve all assigned IPs + +This endpoint allows you to retrieve only assigned IP addresses. + +A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + +GET /ips/assigned + + +response = sg.client.ips.assigned.get() +print response.status_code +print response.body +print response.headers +Create an IP pool. + +This endpoint allows you to create an IP pool. + +Each user can create up to 10 different IP pools. + +IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + +IP pools can only be used with whitelabeled IP addresses. + +If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + +POST /ips/pools + + +data = { + "name": "marketing" +} +response = sg.client.ips.pools.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all IP pools. + +This endpoint allows you to retrieve all of your IP pools. + +IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + +IP pools can only be used with whitelabeled IP addresses. + +If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + +GET /ips/pools + + +response = sg.client.ips.pools.get() +print response.status_code +print response.body +print response.headers +Update an IP pools name. + +This endpoint allows you to update the name of an IP pool. + +IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + +IP pools can only be used with whitelabeled IP addresses. + +If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + +PUT /ips/pools/{pool_name} + + +data = { + "name": "new_pool_name" +} +pool_name = "test_url_param" +response = sg.client.ips.pools._(pool_name).put(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all IPs in a specified pool. + +This endpoint allows you to list all of the IP addresses that are in a specific IP pool. + +IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + +IP pools can only be used with whitelabeled IP addresses. + +If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + +GET /ips/pools/{pool_name} + + +pool_name = "test_url_param" +response = sg.client.ips.pools._(pool_name).get() +print response.status_code +print response.body +print response.headers +Delete an IP pool. + +This endpoint allows you to delete an IP pool. + +IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. + +IP pools can only be used with whitelabeled IP addresses. + +If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. + +DELETE /ips/pools/{pool_name} + + +pool_name = "test_url_param" +response = sg.client.ips.pools._(pool_name).delete() +print response.status_code +print response.body +print response.headers +Add an IP address to a pool + +This endpoint allows you to add an IP address to an IP pool. + +You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. + +A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + +POST /ips/pools/{pool_name}/ips + + +data = { + "ip": "0.0.0.0" +} +pool_name = "test_url_param" +response = sg.client.ips.pools._(pool_name).ips.post(request_body=data) +print response.status_code +print response.body +print response.headers +Remove an IP address from a pool. + +This endpoint allows you to remove an IP address from an IP pool. + +The same IP address can be added to multiple IP pools. + +A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + +DELETE /ips/pools/{pool_name}/ips/{ip} + + +pool_name = "test_url_param" +ip = "test_url_param" +response = sg.client.ips.pools._(pool_name).ips._(ip).delete() +print response.status_code +print response.body +print response.headers +Add an IP to warmup + +This endpoint allows you to enter an IP address into warmup mode. + +SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. + +For more general information about warming up IPs, please see our Classroom. + +POST /ips/warmup + + +data = { + "ip": "0.0.0.0" +} +response = sg.client.ips.warmup.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all IPs currently in warmup + +This endpoint allows you to retrieve all of your IP addresses that are currently warming up. + +SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. + +For more general information about warming up IPs, please see our Classroom. + +GET /ips/warmup + + +response = sg.client.ips.warmup.get() +print response.status_code +print response.body +print response.headers +Retrieve warmup status for a specific IP address + +This endpoint allows you to retrieve the warmup status for a specific IP address. + +SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. + +For more general information about warming up IPs, please see our Classroom. + +GET /ips/warmup/{ip_address} + + +ip_address = "test_url_param" +response = sg.client.ips.warmup._(ip_address).get() +print response.status_code +print response.body +print response.headers +Remove an IP from warmup + +This endpoint allows you to remove an IP address from warmup mode. + +SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. + +For more general information about warming up IPs, please see our Classroom. + +DELETE /ips/warmup/{ip_address} + + +ip_address = "test_url_param" +response = sg.client.ips.warmup._(ip_address).delete() +print response.status_code +print response.body +print response.headers +Retrieve all IP pools an IP address belongs to + +This endpoint allows you to see which IP pools a particular IP address has been added to. + +The same IP address can be added to multiple IP pools. + +A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. + +GET /ips/{ip_address} + + +ip_address = "test_url_param" +response = sg.client.ips._(ip_address).get() +print response.status_code +print response.body +print response.headers + + +MAIL + +Create a batch ID + +This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint. + +If you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. + +More Information: + +Scheduling Parameters > Batch ID + +POST /mail/batch + + +response = sg.client.mail.batch.post() +print response.status_code +print response.body +print response.headers +Validate batch ID + +This endpoint allows you to validate a batch ID. + +If you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. + +More Information: + +Scheduling Parameters > Batch ID + +GET /mail/batch/{batch_id} + + +batch_id = "test_url_param" +response = sg.client.mail.batch._(batch_id).get() +print response.status_code +print response.body +print response.headers +v3 Mail Send + +This endpoint allows you to send email over SendGrids v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our v2 API Reference. + +Top level parameters are referred to as "global". + +Individual fields within the personalizations array will override any other global, or message level, parameters that are defined outside of personalizations. + +For an overview of the v3 Mail Send endpoint, please visit our v3 API Reference + +For more detailed information about how to use the v3 Mail Send endpoint, please visit our Classroom. + +POST /mail/send + +This endpoint has a helper, check it out here. + + +data = { + "asm": { +​ "group_id": 1, +​ "groups_to_display": [ +​ 1, +​ 2, +​ 3 +​ ] + }, + "attachments": [ +​ { +​ "content": "[BASE64 encoded content block here]", +​ "content_id": "ii_139db99fdb5c3704", +​ "disposition": "inline", +​ "filename": "file1.jpg", +​ "name": "file1", +​ "type": "jpg" +​ } + ], + "batch_id": "[YOUR BATCH ID GOES HERE]", + "categories": [ +​ "category1", +​ "category2" + ], + "content": [ +​ { +​ "type": "text/html", +​ "value": "

Hello, world!

" +​ } + ], + "custom_args": { +​ "New Argument 1": "New Value 1", +​ "activationAttempt": "1", +​ "customerAccountNumber": "[CUSTOMER ACCOUNT NUMBER GOES HERE]" + }, + "from": { +​ "email": "sam.smith@example.com", +​ "name": "Sam Smith" + }, + "headers": {}, + "ip_pool_name": "[YOUR POOL NAME GOES HERE]", + "mail_settings": { +​ "bcc": { +​ "email": "ben.doe@example.com", +​ "enable": True +​ }, +​ "bypass_list_management": { +​ "enable": True +​ }, +​ "footer": { +​ "enable": True, +​ "html": "

Thanks
The SendGrid Team

", +​ "text": "Thanks,/n The SendGrid Team" +​ }, +​ "sandbox_mode": { +​ "enable": False +​ }, +​ "spam_check": { +​ "enable": True, +​ "post_to_url": "http://example.com/compliance", +​ "threshold": 3 +​ } + }, + "personalizations": [ +​ { +​ "bcc": [ +​ { +​ "email": "sam.doe@example.com", +​ "name": "Sam Doe" +​ } +​ ], +​ "cc": [ +​ { +​ "email": "jane.doe@example.com", +​ "name": "Jane Doe" +​ } +​ ], +​ "custom_args": { +​ "New Argument 1": "New Value 1", +​ "activationAttempt": "1", +​ "customerAccountNumber": "[CUSTOMER ACCOUNT NUMBER GOES HERE]" +​ }, +​ "headers": { +​ "X-Accept-Language": "en", +​ "X-Mailer": "MyApp" +​ }, +​ "send_at": 1409348513, +​ "subject": "Hello, World!", +​ "substitutions": { +​ "id": "substitutions", +​ "type": "object" +​ }, +​ "to": [ +​ { +​ "email": "john.doe@example.com", +​ "name": "John Doe" +​ } +​ ] +​ } + ], + "reply_to": { +​ "email": "sam.smith@example.com", +​ "name": "Sam Smith" + }, + "sections": { +​ "section": { +​ ":sectionName1": "section 1 text", +​ ":sectionName2": "section 2 text" +​ } + }, + "send_at": 1409348513, + "subject": "Hello, World!", + "template_id": "[YOUR TEMPLATE ID GOES HERE]", + "tracking_settings": { +​ "click_tracking": { +​ "enable": True, +​ "enable_text": True +​ }, +​ "ganalytics": { +​ "enable": True, +​ "utm_campaign": "[NAME OF YOUR REFERRER SOURCE]", +​ "utm_content": "[USE THIS SPACE TO DIFFERENTIATE YOUR EMAIL FROM ADS]", +​ "utm_medium": "[NAME OF YOUR MARKETING MEDIUM e.g. email]", +​ "utm_name": "[NAME OF YOUR CAMPAIGN]", +​ "utm_term": "[IDENTIFY PAID KEYWORDS HERE]" +​ }, +​ "open_tracking": { +​ "enable": True, +​ "substitution_tag": "%opentrack" +​ }, +​ "subscription_tracking": { +​ "enable": True, +​ "html": "If you would like to unsubscribe and stop receiving these emails <% clickhere %>.", +​ "substitution_tag": "<%click here%>", +​ "text": "If you would like to unsubscribe and stop receiving these emails <% click here %>." +​ } + } +} +response = sg.client.mail.send.post(request_body=data) +print response.status_code +print response.body +print response.headers + + +MAIL SETTINGS + +Retrieve all mail settings + +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 or SMTP Relay. + +GET /mail_settings + + +params = {'limit': 1, 'offset': 1} +response = sg.client.mail_settings.get(query_params=params) +print response.status_code +print response.body +print response.headers +Update address whitelist mail settings + +This endpoint allows you to update your current email address whitelist settings. + +The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +PATCH /mail_settings/address_whitelist + + +data = { + "enabled": True, + "list": [ +​ "email1@example.com", +​ "example.com" + ] +} +response = sg.client.mail_settings.address_whitelist.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve address whitelist mail settings + +This endpoint allows you to retrieve your current email address whitelist settings. + +The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +GET /mail_settings/address_whitelist + + +response = sg.client.mail_settings.address_whitelist.get() +print response.status_code +print response.body +print response.headers +Update BCC mail settings + +This endpoint allows you to update your current BCC mail settings. + +When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +PATCH /mail_settings/bcc + + +data = { + "email": "email@example.com", + "enabled": False +} +response = sg.client.mail_settings.bcc.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all BCC mail settings + +This endpoint allows you to retrieve your current BCC mail settings. + +When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +GET /mail_settings/bcc + + +response = sg.client.mail_settings.bcc.get() +print response.status_code +print response.body +print response.headers +Update bounce purge mail settings + +This endpoint allows you to update your current bounce purge settings. + +This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +PATCH /mail_settings/bounce_purge + + +data = { + "enabled": True, + "hard_bounces": 5, + "soft_bounces": 5 +} +response = sg.client.mail_settings.bounce_purge.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve bounce purge mail settings + +This endpoint allows you to retrieve your current bounce purge settings. + +This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +GET /mail_settings/bounce_purge + + +response = sg.client.mail_settings.bounce_purge.get() +print response.status_code +print response.body +print response.headers +Update footer mail settings + +This endpoint allows you to update your current Footer mail settings. + +The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +PATCH /mail_settings/footer + + +data = { + "enabled": True, + "html_content": "...", + "plain_content": "..." +} +response = sg.client.mail_settings.footer.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve footer mail settings + +This endpoint allows you to retrieve your current Footer mail settings. + +The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +GET /mail_settings/footer + + +response = sg.client.mail_settings.footer.get() +print response.status_code +print response.body +print response.headers +Update forward bounce mail settings + +This endpoint allows you to update your current bounce forwarding mail settings. + +Activating this setting allows you to specify an email address to which bounce reports are forwarded. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +PATCH /mail_settings/forward_bounce + + +data = { + "email": "example@example.com", + "enabled": True +} +response = sg.client.mail_settings.forward_bounce.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve forward bounce mail settings + +This endpoint allows you to retrieve your current bounce forwarding mail settings. + +Activating this setting allows you to specify an email address to which bounce reports are forwarded. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +GET /mail_settings/forward_bounce + + +response = sg.client.mail_settings.forward_bounce.get() +print response.status_code +print response.body +print response.headers +Update forward spam mail settings + +This endpoint allows you to update your current Forward Spam mail settings. + +Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +PATCH /mail_settings/forward_spam + + +data = { + "email": "", + "enabled": False +} +response = sg.client.mail_settings.forward_spam.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve forward spam mail settings + +This endpoint allows you to retrieve your current Forward Spam mail settings. + +Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +GET /mail_settings/forward_spam + + +response = sg.client.mail_settings.forward_spam.get() +print response.status_code +print response.body +print response.headers +Update plain content mail settings + +This endpoint allows you to update your current Plain Content mail settings. + +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 or SMTP Relay. + +PATCH /mail_settings/plain_content + + +data = { + "enabled": False +} +response = sg.client.mail_settings.plain_content.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve plain content mail settings + +This endpoint allows you to retrieve your current Plain Content mail settings. + +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 or SMTP Relay. + +GET /mail_settings/plain_content + + +response = sg.client.mail_settings.plain_content.get() +print response.status_code +print response.body +print response.headers +Update spam check mail settings + +This endpoint allows you to update your current spam checker mail settings. + +The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +PATCH /mail_settings/spam_check + + +data = { + "enabled": True, + "max_score": 5, + "url": "url" +} +response = sg.client.mail_settings.spam_check.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve spam check mail settings + +This endpoint allows you to retrieve your current Spam Checker mail settings. + +The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. + +Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. + +GET /mail_settings/spam_check + + +response = sg.client.mail_settings.spam_check.get() +print response.status_code +print response.body +print response.headers +Update template mail settings + +This endpoint allows you to update your current legacy email template settings. + +This setting refers to our original email templates. We currently support more fully featured transactional templates. + +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 or SMTP Relay. + +PATCH /mail_settings/template + + +data = { + "enabled": True, + "html_content": "<% body %>" +} +response = sg.client.mail_settings.template.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve legacy template mail settings + +This endpoint allows you to retrieve your current legacy email template settings. + +This setting refers to our original email templates. We currently support more fully featured transactional templates. + +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 or SMTP Relay. + +GET /mail_settings/template + + +response = sg.client.mail_settings.template.get() +print response.status_code +print response.body +print response.headers + + +MAILBOX PROVIDERS + +Retrieve email statistics by mailbox provider. + +This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider. + +We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. + +Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. + +GET /mailbox_providers/stats + + +params = {'end_date': '2016-04-01', 'mailbox_providers': 'test_string', 'aggregated_by': 'day', 'limit': 1, 'offset': 1, 'start_date': '2016-01-01'} +response = sg.client.mailbox_providers.stats.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +PARTNER SETTINGS + +Returns a list of all partner settings. + +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. + +GET /partner_settings + + +params = {'limit': 1, 'offset': 1} +response = sg.client.partner_settings.get(query_params=params) +print response.status_code +print response.body +print response.headers +Updates New Relic partner settings. + +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. + +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. + +PATCH /partner_settings/new_relic + + +data = { + "enable_subuser_statistics": True, + "enabled": True, + "license_key": "" +} +response = sg.client.partner_settings.new_relic.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Returns all New Relic partner settings. + +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. + +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. + +GET /partner_settings/new_relic + + +response = sg.client.partner_settings.new_relic.get() +print response.status_code +print response.body +print response.headers + + +SCOPES + +Retrieve a list of scopes for which this user has access. + +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, or the Mail API Endpoint. 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 or Classroom. + +GET /scopes + + +response = sg.client.scopes.get() +print response.status_code +print response.body +print response.headers + + +SENDERS + +Create a Sender Identity + +This endpoint allows you to create a new sender identity. + +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. + +POST /senders + + +data = { + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "country": "United States", + "from": { +​ "email": "from@example.com", +​ "name": "Example INC" + }, + "nickname": "My Sender ID", + "reply_to": { +​ "email": "replyto@example.com", +​ "name": "Example INC" + }, + "state": "Colorado", + "zip": "80202" +} +response = sg.client.senders.post(request_body=data) +print response.status_code +print response.body +print response.headers +Get all Sender Identities + +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. + +GET /senders + + +response = sg.client.senders.get() +print response.status_code +print response.body +print response.headers +Update a Sender Identity + +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. + +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. + +PATCH /senders/{sender_id} + + +data = { + "address": "123 Elm St.", + "address_2": "Apt. 456", + "city": "Denver", + "country": "United States", + "from": { +​ "email": "from@example.com", +​ "name": "Example INC" + }, + "nickname": "My Sender ID", + "reply_to": { +​ "email": "replyto@example.com", +​ "name": "Example INC" + }, + "state": "Colorado", + "zip": "80202" +} +sender_id = "test_url_param" +response = sg.client.senders._(sender_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +View a Sender Identity + +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. + +GET /senders/{sender_id} + + +sender_id = "test_url_param" +response = sg.client.senders._(sender_id).get() +print response.status_code +print response.body +print response.headers +Delete a Sender Identity + +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. + +DELETE /senders/{sender_id} + + +sender_id = "test_url_param" +response = sg.client.senders._(sender_id).delete() +print response.status_code +print response.body +print response.headers +Resend Sender Identity Verification + +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. + +POST /senders/{sender_id}/resend_verification + + +sender_id = "test_url_param" +response = sg.client.senders._(sender_id).resend_verification.post() +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 + + +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 Subuser + +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 + +Classroom > How do I add more subusers to my account? + +POST /subusers + + +data = { + "email": "John@example.com", + "ips": [ +​ "1.1.1.1", +​ "2.2.2.2" + ], + "password": "johns_password", + "username": "John@example.com" +} +response = sg.client.subusers.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 + +Classroom > How do I add more subusers to my account? + +GET /subusers + + +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 + +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. + +This endpoint allows you to request the reputations for your subusers. + +GET /subusers/reputations + + +params = {'usernames': 'test_string'} +response = sg.client.subusers.reputations.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve email statistics for your subusers. + +This endpoint allows you to retrieve the email statistics for the given subusers. + +You may retrieve statistics for up to 10 different subusers by including an additional subusers parameter for each additional subuser. + +While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + +For more information, see our User Guide. + +GET /subusers/stats + + +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) +print response.status_code +print response.body +print response.headers +Retrieve monthly stats for all subusers + +This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range. + +While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + +When using the sort_by_metric to sort your stats by a specific metric, you can not sort by the following metrics: +bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops. + +For more information, see our User Guide. + +GET /subusers/stats/monthly + + +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) +print response.status_code +print response.body +print response.headers +Retrieve the totals for each email statistic metric for all subusers. + +This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range. + +While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + +For more information, see our User Guide. + +GET /subusers/stats/sums + + +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) +print response.status_code +print response.body +print response.headers +Enable/disable a subuser + +This endpoint allows you to enable or disable a subuser. + +For more information about Subusers: + +User Guide > Subusers + +Classroom > How do I add more subusers to my account? + +PATCH /subusers/{subuser_name} + + +data = { + "disabled": False +} +subuser_name = "test_url_param" +response = sg.client.subusers._(subuser_name).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Delete a subuser + +This endpoint allows you to delete a subuser. This is a permanent action, once you delete a subuser it cannot be retrieved. + +For more information about Subusers: + +User Guide > Subusers + +Classroom > How do I add more subusers to my account? + +DELETE /subusers/{subuser_name} + + +subuser_name = "test_url_param" +response = sg.client.subusers._(subuser_name).delete() +print response.status_code +print response.body +print response.headers +Update IPs assigned to a subuser + +Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. + +More information: + +How to request more IPs + +IPs can be whitelabeled + +PUT /subusers/{subuser_name}/ips + + +data = [ + "127.0.0.1" +] +subuser_name = "test_url_param" +response = sg.client.subusers._(subuser_name).ips.put(request_body=data) +print response.status_code +print response.body +print response.headers +Update Monitor Settings for a subuser + +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + +PUT /subusers/{subuser_name}/monitor + + +data = { + "email": "example@example.com", + "frequency": 500 +} +subuser_name = "test_url_param" +response = sg.client.subusers._(subuser_name).monitor.put(request_body=data) +print response.status_code +print response.body +print response.headers +Create monitor settings + +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + +POST /subusers/{subuser_name}/monitor + + +data = { + "email": "example@example.com", + "frequency": 50000 +} +subuser_name = "test_url_param" +response = sg.client.subusers._(subuser_name).monitor.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve monitor settings for a subuser + +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + +GET /subusers/{subuser_name}/monitor + + +subuser_name = "test_url_param" +response = sg.client.subusers._(subuser_name).monitor.get() +print response.status_code +print response.body +print response.headers +Delete monitor settings + +Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. + +DELETE /subusers/{subuser_name}/monitor + + +subuser_name = "test_url_param" +response = sg.client.subusers._(subuser_name).monitor.delete() +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. + +While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. + +When using the sort_by_metric to sort your stats by a specific metric, you can not sort by the following metrics: +bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops. + +For more information, see our User Guide. + +GET /subusers/{subuser_name}/stats/monthly + + +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) +print response.status_code +print response.body +print response.headers + + +SUPPRESSION + +Retrieve all blocks + +This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list. + +Blocks 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. + +GET /suppression/blocks + + +params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} +response = sg.client.suppression.blocks.get(query_params=params) +print response.status_code +print response.body +print response.headers +Delete blocks + +This endpoint allows you to delete all email addresses on your blocks list. + +There are two options for deleting blocked emails: + +You can delete all blocked emails by setting delete_all to true in the request body. + +You can delete some blocked emails by specifying the email addresses in an array in the request body. + +Blocks 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. + +DELETE /suppression/blocks + + +data = { + "delete_all": False, + "emails": [ +​ "example1@example.com", +​ "example2@example.com" + ] +} +response = sg.client.suppression.blocks.delete(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a specific block + +This endpoint allows you to retrieve a specific email address from your blocks list. + +Blocks 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. + +GET /suppression/blocks/{email} + + +email = "test_url_param" +response = sg.client.suppression.blocks._(email).get() +print response.status_code +print response.body +print response.headers +Delete a specific block + +This endpoint allows you to delete a specific email address from your blocks list. + +Blocks 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. + +DELETE /suppression/blocks/{email} + + +email = "test_url_param" +response = sg.client.suppression.blocks._(email).delete() +print response.status_code +print response.body +print response.headers +Retrieve all bounces + +This endpoint allows you to retrieve all of your bounces. + +Bounces are messages that are returned to the server that sent it. + +For more information see: + +User Guide > Bounces for more information + +Glossary > Bounces + +GET /suppression/bounces + + +params = {'start_time': 1, 'end_time': 1} +response = sg.client.suppression.bounces.get(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. + +For more information see: + +User Guide > Bounces for more information + +Glossary > Bounces + +Classroom > List Scrubbing Guide + +Note: the delete_all and emails parameters should be used independently of each other as they have different purposes. + +DELETE /suppression/bounces + + +data = { + "delete_all": True, + "emails": [ +​ "example@example.com", +​ "example2@example.com" + ] +} +response = sg.client.suppression.bounces.delete(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a Bounce + +This endpoint allows you to retrieve a specific bounce for a given email address. + +Bounces are messages that are returned to the server that sent it. + +For more information see: + +User Guide > Bounces for more information + +Glossary > Bounces + +Classroom > List Scrubbing Guide + +GET /suppression/bounces/{email} + + +email = "test_url_param" +response = sg.client.suppression.bounces._(email).get() +print response.status_code +print response.body +print response.headers +Delete a bounce + +This endpoint allows you to remove an email address from your bounce list. + +Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email address from your bounce list. + +For more information see: + +User Guide > Bounces for more information + +Glossary > Bounces + +Classroom > List Scrubbing Guide + +DELETE /suppression/bounces/{email} + + +params = {'email_address': 'example@example.com'} +email = "test_url_param" +response = sg.client.suppression.bounces._(email).delete(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve all invalid emails + +This endpoint allows you to retrieve a list of all invalid email addresses. + +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. + +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + +For more information, please see our User Guide. + +GET /suppression/invalid_emails + + +params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} +response = sg.client.suppression.invalid_emails.get(query_params=params) +print response.status_code +print response.body +print response.headers +Delete invalid emails + +This endpoint allows you to remove email addresses from your invalid email address list. + +There are two options for deleting invalid email addresses: + +1) You can delete all invalid email addresses by setting delete_all to true in the request body. +2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. + +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. + +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + +For more information, please see our User Guide. + +DELETE /suppression/invalid_emails + + +data = { + "delete_all": False, + "emails": [ +​ "example1@example.com", +​ "example2@example.com" + ] +} +response = sg.client.suppression.invalid_emails.delete(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a specific invalid email + +This endpoint allows you to retrieve a specific invalid email addresses. + +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. + +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + +For more information, please see our User Guide. + +GET /suppression/invalid_emails/{email} + + +email = "test_url_param" +response = sg.client.suppression.invalid_emails._(email).get() +print response.status_code +print response.body +print response.headers +Delete a specific invalid email + +This endpoint allows you to remove a specific email address from the invalid email address list. + +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. + +Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. + +For more information, please see our User Guide. + +DELETE /suppression/invalid_emails/{email} + + +email = "test_url_param" +response = sg.client.suppression.invalid_emails._(email).delete() +print response.status_code +print response.body +print response.headers +Retrieve a specific spam report + +This endpoint allows you to retrieve a specific spam report. + +Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. + +For more information, please see our User Guide. + +GET /suppression/spam_report/{email} + + +email = "test_url_param" +response = sg.client.suppression.spam_report._(email).get() +print response.status_code +print response.body +print response.headers +Delete a specific spam report + +This endpoint allows you to delete a specific spam report. + +Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. + +For more information, please see our User Guide. + +DELETE /suppression/spam_report/{email} + + +email = "test_url_param" +response = sg.client.suppression.spam_report._(email).delete() +print response.status_code +print response.body +print response.headers +Retrieve all spam reports + +This endpoint allows you to retrieve all spam reports. + +Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. + +For more information, please see our User Guide. + +GET /suppression/spam_reports + + +params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} +response = sg.client.suppression.spam_reports.get(query_params=params) +print response.status_code +print response.body +print response.headers +Delete spam reports + +This endpoint allows you to delete your spam reports. + +There are two options for deleting spam reports: + +1) You can delete all spam reports by setting "delete_all" to true in the request body. +2) You can delete some spam reports by specifying the email addresses in an array in the request body. + +Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. + +For more information, please see our User Guide. + +DELETE /suppression/spam_reports + + +data = { + "delete_all": False, + "emails": [ +​ "example1@example.com", +​ "example2@example.com" + ] +} +response = sg.client.suppression.spam_reports.delete(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all global suppressions + +This endpoint allows you to retrieve a list of all email address that are globally suppressed. + +A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. + +GET /suppression/unsubscribes + + +params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} +response = sg.client.suppression.unsubscribes.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +TEMPLATES + +Create a transactional template. + +This endpoint allows you to create a transactional template. + +Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + +Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. + +POST /templates + + +data = { + "name": "example_name" +} +response = sg.client.templates.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all transactional templates. + +This endpoint allows you to retrieve all transactional templates. + +Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + +Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. + +GET /templates + + +response = sg.client.templates.get() +print response.status_code +print response.body +print response.headers +Edit a transactional template. + +This endpoint allows you to edit a transactional template. + +Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + +Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. + +PATCH /templates/{template_id} + + +data = { + "name": "new_example_name" +} +template_id = "test_url_param" +response = sg.client.templates._(template_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a single transactional template. + +This endpoint allows you to retrieve a single transactional template. + +Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + +Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. + +GET /templates/{template_id} + + +template_id = "test_url_param" +response = sg.client.templates._(template_id).get() +print response.status_code +print response.body +print response.headers +Delete a template. + +This endpoint allows you to delete a transactional template. + +Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. + +Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. + +DELETE /templates/{template_id} + + +template_id = "test_url_param" +response = sg.client.templates._(template_id).delete() +print response.status_code +print response.body +print response.headers +Create a new transactional template version. + +This endpoint allows you to create a new version of a template. + +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + +For more information about transactional templates, please see our User Guide. + +POST /templates/{template_id}/versions + + +data = { + "active": 1, + "html_content": "<%body%>", + "name": "example_version_name", + "plain_content": "<%body%>", + "subject": "<%subject%>", + "template_id": "ddb96bbc-9b92-425e-8979-99464621b543" +} +template_id = "test_url_param" +response = sg.client.templates._(template_id).versions.post(request_body=data) +print response.status_code +print response.body +print response.headers +Edit a transactional template version. + +This endpoint allows you to edit a version of one of your transactional templates. + +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + +For more information about transactional templates, please see our User Guide. + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +template_id string The ID of the original template +version_id string The ID of the template version +PATCH /templates/{template_id}/versions/{version_id} + + +data = { + "active": 1, + "html_content": "<%body%>", + "name": "updated_example_name", + "plain_content": "<%body%>", + "subject": "<%subject%>" +} +template_id = "test_url_param" +version_id = "test_url_param" +response = sg.client.templates._(template_id).versions._(version_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a specific transactional template version. + +This endpoint allows you to retrieve a specific version of a template. + +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + +For more information about transactional templates, please see our User Guide. + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +template_id string The ID of the original template +version_id string The ID of the template version +GET /templates/{template_id}/versions/{version_id} + + +template_id = "test_url_param" +version_id = "test_url_param" +response = sg.client.templates._(template_id).versions._(version_id).get() +print response.status_code +print response.body +print response.headers +Delete a transactional template version. + +This endpoint allows you to delete one of your transactional template versions. + +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + +For more information about transactional templates, please see our User Guide. + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +template_id string The ID of the original template +version_id string The ID of the template version +DELETE /templates/{template_id}/versions/{version_id} + + +template_id = "test_url_param" +version_id = "test_url_param" +response = sg.client.templates._(template_id).versions._(version_id).delete() +print response.status_code +print response.body +print response.headers +Activate a transactional template version. + +This endpoint allows you to activate a version of one of your templates. + +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. + +For more information about transactional templates, please see our User Guide. + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +template_id string The ID of the original template +version_id string The ID of the template version +POST /templates/{template_id}/versions/{version_id}/activate + + +template_id = "test_url_param" +version_id = "test_url_param" +response = sg.client.templates._(template_id).versions._(version_id).activate.post() +print response.status_code +print response.body +print response.headers + + +TRACKING SETTINGS + +Retrieve Tracking Settings + +This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +GET /tracking_settings + + +params = {'limit': 1, 'offset': 1} +response = sg.client.tracking_settings.get(query_params=params) +print response.status_code +print response.body +print response.headers +Update Click Tracking Settings + +This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +PATCH /tracking_settings/click + + +data = { + "enabled": True +} +response = sg.client.tracking_settings.click.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve Click Track Settings + +This endpoint allows you to retrieve your current click tracking setting. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +GET /tracking_settings/click + + +response = sg.client.tracking_settings.click.get() +print response.status_code +print response.body +print response.headers +Update Google Analytics Settings + +This endpoint allows you to update your current setting for Google Analytics. + +For more information about using Google Analytics, please refer to Googles URL Builder and their article on "Best Practices for Campaign Building". + +We default the settings to Googles recommendations. For more information, see Google Analytics Demystified. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +PATCH /tracking_settings/google_analytics + + +data = { + "enabled": True, + "utm_campaign": "website", + "utm_content": "", + "utm_medium": "email", + "utm_source": "sendgrid.com", + "utm_term": "" +} +response = sg.client.tracking_settings.google_analytics.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve Google Analytics Settings + +This endpoint allows you to retrieve your current setting for Google Analytics. + +For more information about using Google Analytics, please refer to Googles URL Builder and their article on "Best Practices for Campaign Building". + +We default the settings to Googles recommendations. For more information, see Google Analytics Demystified. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +GET /tracking_settings/google_analytics + + +response = sg.client.tracking_settings.google_analytics.get() +print response.status_code +print response.body +print response.headers +Update Open Tracking Settings + +This endpoint allows you to update your current settings for open tracking. + +Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +PATCH /tracking_settings/open + + +data = { + "enabled": True +} +response = sg.client.tracking_settings.open.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Get Open Tracking Settings + +This endpoint allows you to retrieve your current settings for open tracking. + +Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +GET /tracking_settings/open + + +response = sg.client.tracking_settings.open.get() +print response.status_code +print response.body +print response.headers +Update Subscription Tracking Settings + +This endpoint allows you to update your current settings for subscription tracking. + +Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +PATCH /tracking_settings/subscription + + +data = { + "enabled": True, + "html_content": "html content", + "landing": "landing page html", + "plain_content": "text content", + "replace": "replacement tag", + "url": "url" +} +response = sg.client.tracking_settings.subscription.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve Subscription Tracking Settings + +This endpoint allows you to retrieve your current settings for subscription tracking. + +Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. + +You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. + +For more information about tracking, please see our User Guide. + +GET /tracking_settings/subscription + + +response = sg.client.tracking_settings.subscription.get() +print response.status_code +print response.body +print response.headers + + +USER + +Get a user's account information. + +This endpoint allows you to retrieve your user account details. + +Your user's account information includes the user's account type and reputation. + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +GET /user/account + + +response = sg.client.user.account.get() +print response.status_code +print response.body +print response.headers +Retrieve your credit balance + +This endpoint allows you to retrieve the current credit balance for your account. + +Your monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our Classroom. + +GET /user/credits + + +response = sg.client.user.credits.get() +print response.status_code +print response.body +print response.headers +Update your account email address + +This endpoint allows you to update the email address currently on file for your account. + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +PUT /user/email + + +data = { + "email": "example@example.com" +} +response = sg.client.user.email.put(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve your account email address + +This endpoint allows you to retrieve the email address currently on file for your account. + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +GET /user/email + + +response = sg.client.user.email.get() +print response.status_code +print response.body +print response.headers +Update your password + +This endpoint allows you to update your password. + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +PUT /user/password + + +data = { + "new_password": "new_password", + "old_password": "old_password" +} +response = sg.client.user.password.put(request_body=data) +print response.status_code +print response.body +print response.headers +Update a user's profile + +This endpoint allows you to update your current profile details. + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. + +PATCH /user/profile + + +data = { + "city": "Orange", + "first_name": "Example", + "last_name": "User" +} +response = sg.client.user.profile.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Get a user's profile + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +GET /user/profile + + +response = sg.client.user.profile.get() +print response.status_code +print response.body +print response.headers +Cancel or pause a scheduled send + +This endpoint allows you to cancel or pause an email that has been scheduled to be sent. + +If the maximum number of cancellations/pauses are added, HTTP 400 will +be returned. + +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + +POST /user/scheduled_sends + + +data = { + "batch_id": "YOUR_BATCH_ID", + "status": "pause" +} +response = sg.client.user.scheduled_sends.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all scheduled sends + +This endpoint allows you to retrieve all cancel/paused scheduled send information. + +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + +GET /user/scheduled_sends + + +response = sg.client.user.scheduled_sends.get() +print response.status_code +print response.body +print response.headers +Update user scheduled send information + +This endpoint allows you to update the status of a scheduled send for the given batch_id. + +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + +PATCH /user/scheduled_sends/{batch_id} + + +data = { + "status": "pause" +} +batch_id = "test_url_param" +response = sg.client.user.scheduled_sends._(batch_id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve scheduled send + +This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific batch_id. + +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + +GET /user/scheduled_sends/{batch_id} + + +batch_id = "test_url_param" +response = sg.client.user.scheduled_sends._(batch_id).get() +print response.status_code +print response.body +print response.headers +Delete a cancellation or pause of a scheduled send + +This endpoint allows you to delete the cancellation/pause of a scheduled send. + +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. + +DELETE /user/scheduled_sends/{batch_id} + + +batch_id = "test_url_param" +response = sg.client.user.scheduled_sends._(batch_id).delete() +print response.status_code +print response.body +print response.headers +Update Enforced TLS settings + +This endpoint allows you to update your current Enforced TLS settings. + +The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the SMTP Ports User Guide for more information on opportunistic TLS. + +Note: If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with TLS required but not supported as the description. + +PATCH /user/settings/enforced_tls + + +data = { + "require_tls": True, + "require_valid_cert": False +} +response = sg.client.user.settings.enforced_tls.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve current Enforced TLS settings. + +This endpoint allows you to retrieve your current Enforced TLS settings. + +The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the SMTP Ports User Guide for more information on opportunistic TLS. + +Note: If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with TLS required but not supported as the description. + +GET /user/settings/enforced_tls + + +response = sg.client.user.settings.enforced_tls.get() +print response.status_code +print response.body +print response.headers +Update your username + +This endpoint allows you to update the username for your account. + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +PUT /user/username + + +data = { + "username": "test_username" +} +response = sg.client.user.username.put(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve your username + +This endpoint allows you to retrieve your current account username. + +Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. + +For more information about your user profile: + +SendGrid Account Settings + +GET /user/username + + +response = sg.client.user.username.get() +print response.status_code +print response.body +print response.headers +Update Event Notification Settings + +This endpoint allows you to update your current event webhook settings. + +If an event type is marked as true, then the event webhook will include information about that event. + +SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + +Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + +PATCH /user/webhooks/event/settings + + +data = { + "bounce": True, + "click": True, + "deferred": True, + "delivered": True, + "dropped": True, + "enabled": True, + "group_resubscribe": True, + "group_unsubscribe": True, + "open": True, + "processed": True, + "spam_report": True, + "unsubscribe": True, + "url": "url" +} +response = sg.client.user.webhooks.event.settings.patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve Event Webhook settings + +This endpoint allows you to retrieve your current event webhook settings. + +If an event type is marked as true, then the event webhook will include information about that event. + +SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + +Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + +GET /user/webhooks/event/settings + + +response = sg.client.user.webhooks.event.settings.get() +print response.status_code +print response.body +print response.headers +Test Event Notification Settings + +This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL. + +SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. + +Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. + +POST /user/webhooks/event/test + + +data = { + "url": "url" +} +response = sg.client.user.webhooks.event.test.post(request_body=data) +print response.status_code +print response.body +print response.headers +Create a parse setting + +This endpoint allows you to create a new inbound parse setting. + +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. + +POST /user/webhooks/parse/settings + + +data = { + "hostname": "myhostname.com", + "send_raw": False, + "spam_check": True, + "url": "http://email.myhosthame.com" +} +response = sg.client.user.webhooks.parse.settings.post(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve all parse settings + +This endpoint allows you to retrieve all of your current inbound parse settings. + +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. + +GET /user/webhooks/parse/settings + + +response = sg.client.user.webhooks.parse.settings.get() +print response.status_code +print response.body +print response.headers +Update a parse setting + +This endpoint allows you to update a specific inbound parse setting. + +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. + +PATCH /user/webhooks/parse/settings/{hostname} + + +data = { + "send_raw": True, + "spam_check": False, + "url": "http://newdomain.com/parse" +} +hostname = "test_url_param" +response = sg.client.user.webhooks.parse.settings._(hostname).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a specific parse setting + +This endpoint allows you to retrieve a specific inbound parse setting. + +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. + +GET /user/webhooks/parse/settings/{hostname} + + +hostname = "test_url_param" +response = sg.client.user.webhooks.parse.settings._(hostname).get() +print response.status_code +print response.body +print response.headers +Delete a parse setting + +This endpoint allows you to delete a specific inbound parse setting. + +The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. + +DELETE /user/webhooks/parse/settings/{hostname} + + +hostname = "test_url_param" +response = sg.client.user.webhooks.parse.settings._(hostname).delete() +print response.status_code +print response.body +print response.headers +Retrieves Inbound Parse Webhook statistics. + +This endpoint allows you to retrieve the statistics for your Parse Webhook usage. + +SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incoming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments. + +There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the Library Index. + +GET /user/webhooks/parse/stats + + +params = {'aggregated_by': 'day', 'limit': 'test_string', 'start_date': '2016-01-01', 'end_date': '2016-04-01', 'offset': 'test_string'} +response = sg.client.user.webhooks.parse.stats.get(query_params=params) +print response.status_code +print response.body +print response.headers + + +WHITELABEL + +Create a domain whitelabel. + +This endpoint allows you to create a whitelabel for one of your domains. + +If you are creating a domain whitelabel that you would like a subuser to use, you have two options: + +Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. + +Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +POST /whitelabel/domains + + +data = { + "automatic_security": False, + "custom_spf": True, + "default": True, + "domain": "example.com", + "ips": [ +​ "192.168.1.1", +​ "192.168.1.2" + ], + "subdomain": "news", + "username": "john@example.com" +} +response = sg.client.whitelabel.domains.post(request_body=data) +print response.status_code +print response.body +print response.headers +List all domain whitelabels. + +This endpoint allows you to retrieve a list of all domain whitelabels you have created. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +GET /whitelabel/domains + + +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 +Get the default domain whitelabel. + +This endpoint allows you to retrieve the default whitelabel for a domain. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +domain string The domain to find a default domain whitelabel for. +GET /whitelabel/domains/default + + +response = sg.client.whitelabel.domains.default.get() +print response.status_code +print response.body +print response.headers +List the domain whitelabel associated with the given user. + +This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. + +For more information on whitelabeling, please see our User Guide + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +username string Username of the subuser to find associated whitelabels for. +GET /whitelabel/domains/subuser + + +response = sg.client.whitelabel.domains.subuser.get() +print response.status_code +print response.body +print response.headers +Disassociate a domain whitelabel from a given user. + +This endpoint allows you to disassociate a specific whitelabel from a subuser. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. + +For more information on whitelabeling, please see our User Guide + +URI Parameters + +URI PARAMETER TYPE REQUIRED? DESCRIPTION +username string required Username for the subuser to find associated whitelabels for. +DELETE /whitelabel/domains/subuser + + +response = sg.client.whitelabel.domains.subuser.delete() +print response.status_code +print response.body +print response.headers +Update a domain whitelabel. + +This endpoint allows you to update the settings for a domain whitelabel. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +PATCH /whitelabel/domains/{domain_id} + + +data = { + "custom_spf": True, + "default": False +} +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 +Retrieve a domain whitelabel. + +This endpoint allows you to retrieve a specific domain whitelabel. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +GET /whitelabel/domains/{domain_id} + + +domain_id = "test_url_param" +response = sg.client.whitelabel.domains._(domain_id).get() +print response.status_code +print response.body +print response.headers +Delete a domain whitelabel. + +This endpoint allows you to delete a domain whitelabel. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +DELETE /whitelabel/domains/{domain_id} + + +domain_id = "test_url_param" +response = sg.client.whitelabel.domains._(domain_id).delete() +print response.status_code +print response.body +print response.headers +Associate a domain whitelabel with a given user. + +This endpoint allows you to associate a specific domain whitelabel with a subuser. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. + +For more information on whitelabeling, please see our User Guide + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +domain_id integer ID of the domain whitelabel to associate with the subuser. +POST /whitelabel/domains/{domain_id}/subuser + + +data = { + "username": "jane@example.com" +} +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 +Add an IP to a domain whitelabel. + +This endpoint allows you to add an IP address to a domain whitelabel. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +id integer ID of the domain to which you are adding an IP +POST /whitelabel/domains/{id}/ips + + +data = { + "ip": "192.168.0.1" +} +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 +Remove an IP from a domain whitelabel. + +This endpoint allows you to remove a domain's IP address from that domain's whitelabel. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +id integer ID of the domain whitelabel to delete the IP from. +ip string IP to remove from the domain whitelabel. +DELETE /whitelabel/domains/{id}/ips/{ip} + + +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 +Validate a domain whitelabel. + +This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated. + +A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. + +For more information on whitelabeling, please see our User Guide + +URI Parameters + +URI PARAMETER TYPE DESCRIPTION +id integer ID of the domain whitelabel to validate. +POST /whitelabel/domains/{id}/validate + + +id = "test_url_param" +response = sg.client.whitelabel.domains._(id).validate.post() +print response.status_code +print response.body +print response.headers +Create an IP whitelabel + +This endpoint allows you to create an IP whitelabel. + +When creating an IP whitelable, you should use the same subdomain that you used when you created a domain whitelabel. + +A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + +For more information, please see our User Guide. + +POST /whitelabel/ips + + +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 +Retrieve all IP whitelabels + +This endpoint allows you to retrieve all of the IP whitelabels that have been created by this account. + +You may include a search key by using the "ip" parameter. This enables you to perform a prefix search for a given IP segment (e.g. "192."). + +A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + +For more information, please see our User Guide. + +GET /whitelabel/ips + + +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 +Retrieve an IP whitelabel + +This endpoint allows you to retrieve an IP whitelabel. + +A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + +For more information, please see our User Guide. + +GET /whitelabel/ips/{id} + + +id = "test_url_param" +response = sg.client.whitelabel.ips._(id).get() +print response.status_code +print response.body +print response.headers +Delete an IP whitelabel + +This endpoint allows you to delete an IP whitelabel. + +A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + +For more information, please see our User Guide. + +DELETE /whitelabel/ips/{id} + + +id = "test_url_param" +response = sg.client.whitelabel.ips._(id).delete() +print response.status_code +print response.body +print response.headers +Validate an IP whitelabel + +This endpoint allows you to validate an IP whitelabel. + +A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. + +For more information, please see our User Guide. + +POST /whitelabel/ips/{id}/validate + + +id = "test_url_param" +response = sg.client.whitelabel.ips._(id).validate.post() +print response.status_code +print response.body +print response.headers +Create a Link Whitelabel + +This endpoint allows you to create a new link whitelabel. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +POST /whitelabel/links + + +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 +Retrieve all link whitelabels + +This endpoint allows you to retrieve all link whitelabels. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +GET /whitelabel/links + + +params = {'limit': 1} +response = sg.client.whitelabel.links.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve a Default Link Whitelabel + +This endpoint allows you to retrieve the default link whitelabel. + +Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: + + +Validated link whitelabels marked as "default" +Legacy link whitelabels (migrated from the whitelabel wizard) +Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net) + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +GET /whitelabel/links/default + + +params = {'domain': 'test_string'} +response = sg.client.whitelabel.links.default.get(query_params=params) +print response.status_code +print response.body +print response.headers +Retrieve Associated Link Whitelabel + +This endpoint allows you to retrieve the associated link whitelabel for a subuser. + +Link whitelables can be associated with subusers from the parent account. This functionality allows +subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account +must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +GET /whitelabel/links/subuser + + +params = {'username': 'test_string'} +response = sg.client.whitelabel.links.subuser.get(query_params=params) +print response.status_code +print response.body +print response.headers +Disassociate a Link Whitelabel + +This endpoint allows you to disassociate a link whitelabel from a subuser. + +Link whitelables can be associated with subusers from the parent account. This functionality allows +subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account +must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +DELETE /whitelabel/links/subuser + + +params = {'username': 'test_string'} +response = sg.client.whitelabel.links.subuser.delete(query_params=params) +print response.status_code +print response.body +print response.headers +Update a Link Whitelabel + +This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +PATCH /whitelabel/links/{id} + + +data = { + "default": True +} +id = "test_url_param" +response = sg.client.whitelabel.links._(id).patch(request_body=data) +print response.status_code +print response.body +print response.headers +Retrieve a Link Whitelabel + +This endpoint allows you to retrieve a specific link whitelabel. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +GET /whitelabel/links/{id} + + +id = "test_url_param" +response = sg.client.whitelabel.links._(id).get() +print response.status_code +print response.body +print response.headers +Delete a Link Whitelabel + +This endpoint allows you to delete a link whitelabel. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +DELETE /whitelabel/links/{id} + + +id = "test_url_param" +response = sg.client.whitelabel.links._(id).delete() +print response.status_code +print response.body +print response.headers +Validate a Link Whitelabel + +This endpoint allows you to validate a link whitelabel. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +POST /whitelabel/links/{id}/validate + + +id = "test_url_param" +response = sg.client.whitelabel.links._(id).validate.post() +print response.status_code +print response.body +print response.headers +Associate a Link Whitelabel + +This endpoint allows you to associate a link whitelabel with a subuser account. + +Link whitelables can be associated with subusers from the parent account. This functionality allows +subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account +must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. + +Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. + +For more information, please see our User Guide. + +POST /whitelabel/links/{link_id}/subuser + + +data = { + "username": "jane@example.com" +} +link_id = "test_url_param" +response = sg.client.whitelabel.links._(link_id).subuser.post(request_body=data) +print response.status_code +print response.body +print response.headersPOST /access_settings/whitelist ```python diff --git a/docker-test/README.md b/docker-test/README.md index d44ebf759..487a17ee6 100644 --- a/docker-test/README.md +++ b/docker-test/README.md @@ -20,7 +20,7 @@ This Docker image contains: - `python setup.py install` 2. [Install Docker](https://docs.docker.com/install/) 3. [Setup local environment variable SENDGRID_API_KEY](https://github.com/sendgrid/sendgrid-php#setup-environment-variables) -4. Build Docker image, run Docker container, login to the Docker container +4. Build a Docker image, run Docker container, login to the Docker container - `docker image build --tag="sendgrid/python3.6" ./docker-test` - `docker run -itd --name="sendgrid_python3.6" -v $(pwd):/root/sendgrid-python sendgrid/python3.6 /bin/bash` 5. Run the tests within the Docker container diff --git a/docker/USAGE.md b/docker/USAGE.md index d869a77ce..0d3f90b90 100644 --- a/docker/USAGE.md +++ b/docker/USAGE.md @@ -77,7 +77,7 @@ Note that the paths you specify in `-v` must be absolute. 1. Install docker-compose on your machine. 2. Must copy sendgrid.env to .env file. -3. Edit .env file for yours versions and paths. +3. Edit .env file for your versions and paths. 4. Must create env folder for clone yours repo. 5. Have fun! :D diff --git a/proposals/mail-helper-refactor.md b/proposals/mail-helper-refactor.md index 5a0127fd6..a057b38e0 100644 --- a/proposals/mail-helper-refactor.md +++ b/proposals/mail-helper-refactor.md @@ -196,7 +196,7 @@ msg.custom_arg = [ msg.send_at = SendAt(1461775052, p=1) -# The values below this comment are global to entire message +# The values below this comment are global to the entire message msg.global_subject = Subject('Sending with SendGrid is Fun') diff --git a/sendgrid/helpers/inbound/README.md b/sendgrid/helpers/inbound/README.md index bc69d1189..f8bec75ce 100644 --- a/sendgrid/helpers/inbound/README.md +++ b/sendgrid/helpers/inbound/README.md @@ -1,4 +1,4 @@ -**This helper is a stand alone module to help get you started consuming and processing Inbound Parse data.** +**This helper is a stand-alone module to help get you started consuming and processing Inbound Parse data.** ## Table of Contents diff --git a/use_cases/asynchronous_mail_send.md b/use_cases/asynchronous_mail_send.md index 57dd61b2a..253b07a0c 100644 --- a/use_cases/asynchronous_mail_send.md +++ b/use_cases/asynchronous_mail_send.md @@ -2,7 +2,7 @@ ## Using `asyncio` (3.5+) -The built-in `asyncio` library can be used to send email in a non-blocking manner. `asyncio` helps us execute mail sending in a separate context, allowing us to continue execution of business logic without waiting for all our emails to send first. +The built-in `asyncio` library can be used to send email in a non-blocking manner. `asyncio` helps us execute mail sending in a separate context, allowing us to continue the execution of business logic without waiting for all our emails to send first. ```python import sendgrid diff --git a/use_cases/aws.md b/use_cases/aws.md index d07d5769c..83f3ca61c 100644 --- a/use_cases/aws.md +++ b/use_cases/aws.md @@ -2,14 +2,14 @@ This tutorial explains how to set up a simple "Hello Email" app on AWS, using the AWS CodeStar service. -We'll be creating a basic web service to send email via SendGrid. The application will run on AWS Lambda, and the "endpoint" will be via AWS API Gateway. +We'll be creating a basic web service to send an email via SendGrid. The application will run on AWS Lambda, and the "endpoint" will be via AWS API Gateway. -The neat thing is that CodeStar provides all of this in a pre-configured package. We just have to make some config changes, and push our code. +The neat thing is that CodeStar provides all of this in a pre-configured package. We just have to make some config changes and push our code. -Once this tutorial is complete, you'll have a basic web service for sending email that can be invoked via a link to your newly created API endpoint. +Once this tutorial is complete, you'll have a basic web service for sending an email that can be invoked via a link to your newly created API endpoint. ### Prerequisites -Python 2.6, 2.7, 3.4, or 3.5 are supported by the sendgrid Python library, however I was able to utilize 3.6 with no issue. +Python 2.6, 2.7, 3.4, or 3.5 are supported by the sendgrid Python library, however, I was able to utilize 3.6 with no issue. Before starting this tutorial, you will need to have access to an AWS account in which you are allowed to provision resources. This tutorial also assumes you've already created a SendGrid account with free-tier access. Finally, it is highly recommended you utilize [virtualenv](https://virtualenv.pypa.io/en/stable/). @@ -19,18 +19,18 @@ Before starting this tutorial, you will need to have access to an AWS account in ## Getting Started ### Create AWS CodeStar Project -Log in to your AWS account and go to the AWS CodeStar service. Click "Start a project". For this tutorial we're going to choose a Python Web service, utilizing AWS Lambda. You can use the filters on the left hand side of the UI to narrow down the available choices. +Log in to your AWS account and go to the AWS CodeStar service. Click "Start a project". For this tutorial we're going to choose a Python Web service, utilizing AWS Lambda. You can use the filters on the left-hand side of the UI to narrow down the available choices. -After you've selected the template, you're asked to provide a name for your project. Go ahead and name it "hello-email". Once you've entered a name, click "Create Project" in the lower right hand corner. You can then choose which tools you want to use to interact with the project. For this tutorial, we'll be choosing "Command Line". +After you've selected the template, you're asked to provide a name for your project. Go ahead and name it "hello-email". Once you've entered a name, click "Create Project" in the lower right-hand corner. You can then choose which tools you want to use to interact with the project. For this tutorial, we'll be choosing the "Command Line". -Once that is completed, you'll be given some basic steps to get Git installed and setup, and instructions for connecting to the AWS CodeCommit(git) repository. You can either use HTTPS, or SSH. Instructions for setting up either are provided. +Once that is completed, you'll be given some basic steps to get Git installed and setup, and instructions for connecting to the AWS CodeCommit(git) repository. You can either use HTTPS or SSH. Instructions for setting up either are provided. -Go ahead and clone the Git repository link after it is created. You may need to click "Skip" in the lower right hand corner to proceed. +Go ahead and clone the Git repository link after it is created. You may need to click "Skip" in the lower right-hand corner to proceed. -Once that's done, you've successfully created a CodeStar project! You should be at the dashboard, with a view of the wiki, change log, build pipeline, and application endpoint. +Once that's done, you've successfully created a CodeStar project! You should be at the dashboard, with a view of the wiki, changelog, build a pipeline, and application endpoint. ### Create SendGrid API Key -Log in to your SendGrid account. Click on your user name on the left hand side of the UI and choose "Setup Guide" from the drop-down menu. On the "Welcome" menu, choose "Send Your First Email", and then "Integrate using our Web API or SMTP relay." Choose "Web API" as the recommended option on the next screen, as we'll be using that for this tutorial. For more information about creating API keys, see https://sendgrid.com/docs/Classroom/Send/How_Emails_Are_Sent/api_keys.html +Log in to your SendGrid account. Click on your username on the left-hand side of the UI and choose "Setup Guide" from the drop-down menu. On the "Welcome" menu, choose "Send Your First Email", and then "Integrate using our Web API or SMTP relay." Choose "Web API" as the recommended option on the next screen, as we'll be using that for this tutorial. For more information about creating API keys, see https://sendgrid.com/docs/Classroom/Send/How_Emails_Are_Sent/api_keys.html On the next menu, you have the option to choose what programming language you'll be using. The obvious choice for this tutorial will be Python. @@ -100,7 +100,7 @@ virtualenv venv source ./venv/bin/activate ``` -Prior to being able to deploy our Python code, we'll need to install the sendgrid Python module *locally*. One of the idiosyncracies of AWS Lambda is that all library and module dependencies that aren't part of the standard library have to be included with the code/build artifact. Virtual environments do not translate to the Lambda runtime environment. +Prior to being able to deploy our Python code, we'll need to install the sendgrid Python module *locally*. One of the idiosyncrasies of AWS Lambda is that all library and module dependencies that aren't part of the standard library have to be included with the code/build artifact. Virtual environments do not translate to the Lambda runtime environment. In the root project directory, run the following command: ``` @@ -169,4 +169,4 @@ SENDGRID_API_KEY Now, go back to your project dashboard in CodeStar. Click on the link under "Application endpoints". After a moment, you should be greeted with JSON output indicating an email was successfully sent. -Congratulations, you've just used serverless technology to create an email sending app in AWS! \ No newline at end of file +Congratulations, you've just used serverless technology to create an email sending the app in AWS! \ No newline at end of file diff --git a/use_cases/django.md b/use_cases/django.md index 554e5fa21..c6b14dad2 100644 --- a/use_cases/django.md +++ b/use_cases/django.md @@ -1,4 +1,4 @@ -# Create a Django app to send email with SendGrid +# Create a Django app to send an email with SendGrid This tutorial explains how we set up a simple Django app to send an email with the SendGrid Python SDK and how we deploy our app to Heroku. @@ -75,7 +75,7 @@ def index(request): return HttpResponse('Email Sent!') ``` -**Note:** It would be best to change your to email from `test@example.com` to your own email, so that you can see the email you receive. +**Note:** It would be best to change your to email from `test@example.com` to your own email so that you can see the email you receive. Now the folder structure should look like this: @@ -92,7 +92,7 @@ hello-sendgrid └── requirements.txt ``` -Next we open the file `urls.py` in order to add the view we have just created to the Django URL dispatcher. +Next, we open the file `urls.py` in order to add the view we have just created to the Django URL dispatcher. ```python from django.conf.urls import url @@ -119,7 +119,7 @@ $ python manage.py migrate $ python manage.py runserver ``` -By default, it starts the development server at `http://127.0.0.1:8000/`. To test if we can send email or not, go to `http://127.0.0.1:8000/sendgrid/`. If it works, we should see the page says "Email Sent!". +By default, it starts the development server at `http://127.0.0.1:8000/`. To test if we can send an email or not, go to `http://127.0.0.1:8000/sendgrid/`. If it works, we should see the page says "Email Sent!". **Note:** If you use `test@example.com` as your from email, it's likely to go to your spam folder. To have the emails show up in your inbox, try using an email address at the domain you registered your SendGrid account. diff --git a/use_cases/flask_heroku.md b/use_cases/flask_heroku.md index ef0fa599a..fd55c77b5 100644 --- a/use_cases/flask_heroku.md +++ b/use_cases/flask_heroku.md @@ -1,4 +1,4 @@ -# Create a Flask app to send email with SendGrid +# Create a Flask app to send an email with SendGrid This tutorial explains how to deploy a simple Flask app, to send an email using the SendGrid Python SDK, on Heroku. From 935a4d70a0259b557452bb49278ef8d6947fa91d Mon Sep 17 00:00:00 2001 From: Xeon Zolt Date: Mon, 15 Oct 2018 15:28:20 +0530 Subject: [PATCH 2/3] fixed changes suggested --- CODE_OF_CONDUCT.md | 16 ++++++++-------- CONTRIBUTING.md | 8 ++++---- TROUBLESHOOTING.md | 2 +- use_cases/aws.md | 20 ++++++++++---------- use_cases/django.md | 6 +++--- use_cases/flask_heroku.md | 2 +- 6 files changed, 27 insertions(+), 27 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 670a82f62..31743bc0e 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,6 +1,6 @@ # SendGrid Community Code of Conduct - The SendGrid open source community is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences successes and continued growth. When you're working with members of the community, we encourage you to follow these guidelines, which help steer our interactions and strive to maintain a positive, successful and growing community. + The SendGrid open source community is made up of members from around the globe with a diverse set of skills, personalities, and experiences. It is through these differences that our community experiences successes and continued growth. When you're working with members of the community, we encourage you to follow these guidelines, which help steer our interactions and strive to maintain a positive, successful and growing community. ### Be Open Members of the community are open to collaboration, whether it's on pull requests, code reviews, approvals, issues or otherwise. We're receptive to constructive comments and criticism, as the experiences and skill sets of all members contribute to the whole of our efforts. We're accepting of all who wish to take part in our activities, fostering an environment where anyone can participate, and everyone can make a difference. @@ -9,15 +9,15 @@ Members of the community are considerate of their peers, which include other contributors and users of SendGrid. We're thoughtful when addressing the efforts of others, keeping in mind that often the labor was completed with the intent of the good of the community. We're attentive in our communications, whether in person or online, and we're tactful when approaching differing views. ### Be Respectful - Members of the community are respectful. We're respectful of others, their positions, their skills, their commitments ,and their efforts. We're respectful of the volunteer efforts that permeate the SendGrid community. We're respectful of the processes outlined in the community, and we work within them. When we disagree, we are courteous in raising our issues. Overall, we're good with each other. We contribute to this community not because we have to, but because we want to. If we remember that, these guidelines will come naturally. + Members of the community are respectful. We're respectful of others, their positions, their skills, their commitments, and their efforts. We're respectful of the volunteer efforts that permeate the SendGrid community. We're respectful of the processes outlined in the community, and we work within them. When we disagree, we are courteous in raising our issues. Overall, we're good with each other. We contribute to this community not because we have to, but because we want to. If we remember that, these guidelines will come naturally. - ## Additional Guidance + ## Additional Guidance ### Disclose Potential Conflicts of Interest Community discussions often involve interested parties. We expect participants to be aware when they are conflicted due to employment or other projects they are involved in and disclose those interests to other project members. When in doubt, over-disclose. Perceived conflicts of interest are important to address so that the community’s decisions are credible even when unpopular, difficult or favorable to the interests of one group over another. ### Interpretation - This Code is not exhaustive or complete. It is not a rulebook; it serves to distill our common understanding of a collaborative, shared environment and goals. We expect it to be followed in spirit as much as in the letter. When in doubt, try to abide by [SendGrid’s cultural values](https://sendgrid.com/blog/employee-engagement-the-4h-way) defined by our “4H’s”: Happy, Hungry, Humble and Honest. + This Code is not exhaustive or complete. It is not a rulebook; it serves to distill our common understanding of a collaborative, shared environment and goals. We expect it to be followed in spirit as much as in the letter. When in doubt, try to abide by [SendGrid’s cultural values](https://sendgrid.com/blog/employee-engagement-the-4h-way) defined by our “4H’s”: Happy, Hungry, Humble and Honest. ### Enforcement Most members of the SendGrid community always comply with this Code, not because of the existence of this Code, but because they have long experience participating in open source communities where the conduct described above is normal and expected. However, failure to observe this Code may be grounds for suspension, reporting the user for abuse or changing permissions for outside contributors. @@ -30,12 +30,12 @@ **Contact the Moderators** - You can reach the SendGrid moderators by emailing dx@sendgrid.com. ## Submission to SendGrid Repositories - Finally, just a reminder, changes to the SendGrid repositories will only be accepted upon completion of the [SendGrid Contributor Agreement](https://cla.sendgrid.com). + Finally, just a reminder, changes to the SendGrid repositories will only be accepted upon completion of the [SendGrid Contributor Agreement](https://cla.sendgrid.com). ## Attribution SendGrid thanks the following, on which it draws for content and inspiration: - [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/) - [Open Source Initiative General Code of Conduct](https://opensource.org/codeofconduct) - [Apache Code of Conduct](https://www.apache.org/foundation/policies/conduct.html) + [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/) + [Open Source Initiative General Code of Conduct](https://opensource.org/codeofconduct) + [Apache Code of Conduct](https://www.apache.org/foundation/policies/conduct.html) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 90f8a1f42..f3bba6d65 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,7 +62,7 @@ We welcome direct contributions to the sendgrid-python code base. Thank you! ### Development Environment ### #### There are two ways to get set up: #### #### 1. Using Docker #### -This is usually the easiest and fastest way to get set up. +This is usually the easiest and fastest way to get set up. You can use our Docker image to avoid setting up the development environment yourself. See [USAGE.md](https://github.com/sendgrid/sendgrid-python/blob/master/docker/USAGE.md). #### - OR - #### @@ -191,10 +191,10 @@ Please run your code through: ```bash # Clone your fork of the repo into the current directory git clone https://github.com/sendgrid/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 ``` @@ -213,7 +213,7 @@ Please run your code through: git checkout -b ``` -4. Commit your changes in logical chunks. Please adhere to these [git commits +4. Commit your changes in logical chunks. Please adhere to these [git commit message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) or your code is unlikely to be merged into the main project. Use Git's [interactive rebase](https://help.github.com/articles/interactive-rebase) diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index a33919a26..97eca9b55 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -95,7 +95,7 @@ If you are using a [requirements file](https://pip.readthedocs.io/en/1.1/require ## Versioning Convention -We follow the MAJOR.MINOR.PATCH versioning scheme as described by [SemVer.org](http://semver.org). Therefore, we recommend that you always pin (or vendor) the particular version you are working with your code and never auto-update to the latest version. Especially when there is a MAJOR point release since that is guaranteed to be a breaking change. Changes are documented in the [CHANGELOG](https://github.com/sendgrid/sendgrid-python/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-python/releases) section. +We follow the MAJOR.MINOR.PATCH versioning scheme as described by [SemVer.org](http://semver.org). Therefore, we recommend that you always pin (or vendor) the particular version you are working with in your code and never auto-update to the latest version. Especially when there is a MAJOR point release since that is guaranteed to be a breaking change. Changes are documented in the [CHANGELOG](https://github.com/sendgrid/sendgrid-python/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-python/releases) section. ## Viewing the Request Body diff --git a/use_cases/aws.md b/use_cases/aws.md index 83f3ca61c..2d8d25b00 100644 --- a/use_cases/aws.md +++ b/use_cases/aws.md @@ -2,11 +2,11 @@ This tutorial explains how to set up a simple "Hello Email" app on AWS, using the AWS CodeStar service. -We'll be creating a basic web service to send an email via SendGrid. The application will run on AWS Lambda, and the "endpoint" will be via AWS API Gateway. +We'll be creating a basic web service to send email via SendGrid. The application will run on AWS Lambda, and the "endpoint" will be via AWS API Gateway. The neat thing is that CodeStar provides all of this in a pre-configured package. We just have to make some config changes and push our code. -Once this tutorial is complete, you'll have a basic web service for sending an email that can be invoked via a link to your newly created API endpoint. +Once this tutorial is complete, you'll have a basic web service for sending email that can be invoked via a link to your newly created API endpoint. ### Prerequisites Python 2.6, 2.7, 3.4, or 3.5 are supported by the sendgrid Python library, however, I was able to utilize 3.6 with no issue. @@ -21,13 +21,13 @@ Before starting this tutorial, you will need to have access to an AWS account in ### Create AWS CodeStar Project Log in to your AWS account and go to the AWS CodeStar service. Click "Start a project". For this tutorial we're going to choose a Python Web service, utilizing AWS Lambda. You can use the filters on the left-hand side of the UI to narrow down the available choices. -After you've selected the template, you're asked to provide a name for your project. Go ahead and name it "hello-email". Once you've entered a name, click "Create Project" in the lower right-hand corner. You can then choose which tools you want to use to interact with the project. For this tutorial, we'll be choosing the "Command Line". +After you've selected the template, you're asked to provide a name for your project. Go ahead and name it "hello-email". Once you've entered a name, click "Create Project" in the lower right-hand corner. You can then choose which tools you want to use to interact with the project. For this tutorial, we'll be choosing "Command Line". -Once that is completed, you'll be given some basic steps to get Git installed and setup, and instructions for connecting to the AWS CodeCommit(git) repository. You can either use HTTPS or SSH. Instructions for setting up either are provided. +Once that is completed, you'll be given some basic steps to get Git installed and setup, and instructions for connecting to the AWS CodeCommit(git) repository. You can either use HTTPS or SSH. Instructions for setting up either are provided. Go ahead and clone the Git repository link after it is created. You may need to click "Skip" in the lower right-hand corner to proceed. -Once that's done, you've successfully created a CodeStar project! You should be at the dashboard, with a view of the wiki, changelog, build a pipeline, and application endpoint. +Once that's done, you've successfully created a CodeStar project! You should be at the dashboard, with a view of the wiki, changelog, build pipeline, and application endpoint. ### Create SendGrid API Key Log in to your SendGrid account. Click on your username on the left-hand side of the UI and choose "Setup Guide" from the drop-down menu. On the "Welcome" menu, choose "Send Your First Email", and then "Integrate using our Web API or SMTP relay." Choose "Web API" as the recommended option on the next screen, as we'll be using that for this tutorial. For more information about creating API keys, see https://sendgrid.com/docs/Classroom/Send/How_Emails_Are_Sent/api_keys.html @@ -44,7 +44,7 @@ For the rest of the tutorial, we'll be working out of the Git repository we clon ``` $ cd hello-email ``` -note: this assumes you cloned the Git repo inside your current directory. My directory is: +note: this assumes you cloned the Git repo inside your current directory. My directory is: ``` ~/projects/hello-email @@ -100,7 +100,7 @@ virtualenv venv source ./venv/bin/activate ``` -Prior to being able to deploy our Python code, we'll need to install the sendgrid Python module *locally*. One of the idiosyncrasies of AWS Lambda is that all library and module dependencies that aren't part of the standard library have to be included with the code/build artifact. Virtual environments do not translate to the Lambda runtime environment. +Prior to being able to deploy our Python code, we'll need to install the sendgrid Python module *locally*. One of the idiosyncrasies of AWS Lambda is that all library and module dependencies that aren't part of the standard library have to be included with the code/build artifact. Virtual environments do not translate to the Lambda runtime environment. In the root project directory, run the following command: ``` @@ -157,7 +157,7 @@ $ git commit -m 'hello-email app' $ git push ``` -Once the code is successfully pushed, head back to the AWS CodeStar dashboard for your project. After your commit successfully registers, an automated build and deployment process should kick off. +Once the code is successfully pushed, head back to the AWS CodeStar dashboard for your project. After your commit successfully registers, an automated build and deployment process should kick off. One more step left before our application will work correctly. After your code has bee deployed, head to the AWS Lambda console. Click on your function name, which should start with `awscodestar-hello-email-lambda-`, or similar. @@ -167,6 +167,6 @@ Scroll down to the "Environment Variables" section. Here we need to populate our SENDGRID_API_KEY ``` -Now, go back to your project dashboard in CodeStar. Click on the link under "Application endpoints". After a moment, you should be greeted with JSON output indicating an email was successfully sent. +Now, go back to your project dashboard in CodeStar. Click on the link under "Application endpoints". After a moment, you should be greeted with JSON output indicating an email was successfully sent. -Congratulations, you've just used serverless technology to create an email sending the app in AWS! \ No newline at end of file +Congratulations, you've just used serverless technology to create an email sending app in AWS! diff --git a/use_cases/django.md b/use_cases/django.md index c6b14dad2..aae2d3c04 100644 --- a/use_cases/django.md +++ b/use_cases/django.md @@ -1,4 +1,4 @@ -# Create a Django app to send an email with SendGrid +# Create a Django app to send email with SendGrid This tutorial explains how we set up a simple Django app to send an email with the SendGrid Python SDK and how we deploy our app to Heroku. @@ -119,7 +119,7 @@ $ python manage.py migrate $ python manage.py runserver ``` -By default, it starts the development server at `http://127.0.0.1:8000/`. To test if we can send an email or not, go to `http://127.0.0.1:8000/sendgrid/`. If it works, we should see the page says "Email Sent!". +By default, it starts the development server at `http://127.0.0.1:8000/`. To test if we can send email or not, go to `http://127.0.0.1:8000/sendgrid/`. If it works, we should see the page says "Email Sent!". **Note:** If you use `test@example.com` as your from email, it's likely to go to your spam folder. To have the emails show up in your inbox, try using an email address at the domain you registered your SendGrid account. @@ -198,4 +198,4 @@ $ git commit -am "Create simple Hello Email Django app using SendGrid" $ git push heroku master ``` -After that, let's verify if our app is working or not by accessing the root domain of your Heroku app. You should see the page says "Email Sent!" and on the Activity Feed page in the SendGrid dashboard, you should see a new feed with the email you set in the code. \ No newline at end of file +After that, let's verify if our app is working or not by accessing the root domain of your Heroku app. You should see the page says "Email Sent!" and on the Activity Feed page in the SendGrid dashboard, you should see a new feed with the email you set in the code. diff --git a/use_cases/flask_heroku.md b/use_cases/flask_heroku.md index fd55c77b5..ef0fa599a 100644 --- a/use_cases/flask_heroku.md +++ b/use_cases/flask_heroku.md @@ -1,4 +1,4 @@ -# Create a Flask app to send an email with SendGrid +# Create a Flask app to send email with SendGrid This tutorial explains how to deploy a simple Flask app, to send an email using the SendGrid Python SDK, on Heroku. From 2793955714386fb0312dfdc51018487f95dfd8e1 Mon Sep 17 00:00:00 2001 From: Harsh Lathwal Date: Thu, 18 Oct 2018 01:16:12 +0530 Subject: [PATCH 3/3] removed similar data and kept fixes --- USAGE.md | 4711 +----------------------------------------------------- 1 file changed, 45 insertions(+), 4666 deletions(-) diff --git a/USAGE.md b/USAGE.md index ea2beae39..40f0472f8 100644 --- a/USAGE.md +++ b/USAGE.md @@ -70,4628 +70,7 @@ IP Access Management allows you to control which IP addresses can be used to acc For more information, please see our [User Guide](http://sendgrid.com/docs/User_Guide/Settings/ip_access_management.html). -This documentation is based on our OAI specification. - -INITIALIZATION - - -import sendgrid -import os - - -sg = sendgrid.SendGridAPIClient(apikey=os.environ.get('SENDGRID_API_KEY')) -Table of Contents - -ACCESS SETTINGS - -ALERTS - -API KEYS - -ASM - -BROWSERS - -CAMPAIGNS - -CATEGORIES - -CLIENTS - -CONTACTDB - -DEVICES - -GEO - -IPS - -MAIL - -MAIL SETTINGS - -MAILBOX PROVIDERS - -PARTNER SETTINGS - -SCOPES - -SENDERS - -STATS - -SUBUSERS - -SUPPRESSION - -TEMPLATES - -TRACKING SETTINGS - -USER - -WHITELABEL - - - -ACCESS SETTINGS - -Retrieve all recent access attempts - -This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your account either through the User Interface or the API. - -IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - -For more information, please see our User Guide. - -GET /access_settings/activity - - -params = {'limit': 1} -response = sg.client.access_settings.activity.get(query_params=params) -print response.status_code -print response.body -print response.headers -Add one or more IPs to the whitelist - -This endpoint allows you to add one or more IP addresses to your IP whitelist. - -When adding an IP to your whitelist, include the IP address in an array. You can whitelist one IP at a time, or you can whitelist multiple IPs at once. - -IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - -For more information, please see our User Guide. - -POST /access_settings/whitelist - - -data = { - "ips": [ -​ { -​ "ip": "192.168.1.1" -​ }, -​ { -​ "ip": "192.*.*.*" -​ }, -​ { -​ "ip": "192.168.1.3/32" -​ } - ] -} -response = sg.client.access_settings.whitelist.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a list of currently whitelisted IPs - -This endpoint allows you to retrieve a list of IP addresses that are currently whitelisted. - -IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - -For more information, please see our User Guide. - -GET /access_settings/whitelist - - -response = sg.client.access_settings.whitelist.get() -print response.status_code -print response.body -print response.headers -Remove one or more IPs from the whitelist - -This endpoint allows you to remove one or more IPs from your IP whitelist. - -You can remove one IP at a time, or you can remove multiple IP addresses. - -IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - -For more information, please see our User Guide. - -DELETE /access_settings/whitelist - - -data = { - "ids": [ -​ 1, -​ 2, -​ 3 - ] -} -response = sg.client.access_settings.whitelist.delete(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a specific whitelisted IP - -This endpoint allows you to retrieve a specific IP address that has been whitelisted. - -You must include the ID for the specific IP address you want to retrieve in your call. - -IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - -For more information, please see our User Guide. - -GET /access_settings/whitelist/{rule_id} - - -rule_id = "test_url_param" -response = sg.client.access_settings.whitelist._(rule_id).get() -print response.status_code -print response.body -print response.headers -Remove a specific IP from the whitelist - -This endpoint allows you to remove a specific IP address from your IP whitelist. - -When removing a specific IP address from your whitelist, you must include the ID in your call. - -IP Access Management allows you to control which IP addresses can be used to access your account, either through the User Interface or the API. There is no limit to the number of IP addresses that you can add to your whitelist. It is possible to remove your own IP address from the whitelist, thus preventing yourself from accessing your account. - -For more information, please see our User Guide. - -DELETE /access_settings/whitelist/{rule_id} - - -rule_id = "test_url_param" -response = sg.client.access_settings.whitelist._(rule_id).delete() -print response.status_code -print response.body -print response.headers - - -ALERTS - -Create a new Alert - -This endpoint allows you to create a new alert. - -Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - -Usage alerts allow you to set the threshold at which an alert will be sent. - -Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - -For more information about alerts, please see our User Guide. - -POST /alerts - - -data = { - "email_to": "example@example.com", - "frequency": "daily", - "type": "stats_notification" -} -response = sg.client.alerts.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all alerts - -GET /alerts - - -response = sg.client.alerts.get() -print response.status_code -print response.body -print response.headers -Update an alert - -This endpoint allows you to update an alert. - -Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - -Usage alerts allow you to set the threshold at which an alert will be sent. - -Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - -For more information about alerts, please see our User Guide. - -PATCH /alerts/{alert_id} - - -data = { - "email_to": "example@example.com" -} -alert_id = "test_url_param" -response = sg.client.alerts._(alert_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a specific alert - -This endpoint allows you to retrieve a specific alert. - -Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - -Usage alerts allow you to set the threshold at which an alert will be sent. - -Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - -For more information about alerts, please see our User Guide. - -GET /alerts/{alert_id} - - -alert_id = "test_url_param" -response = sg.client.alerts._(alert_id).get() -print response.status_code -print response.body -print response.headers -Delete an alert - -This endpoint allows you to delete an alert. - -Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics. - -Usage alerts allow you to set the threshold at which an alert will be sent. - -Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, "daily", "weekly", or "monthly". - -For more information about alerts, please see our User Guide. - -DELETE /alerts/{alert_id} - - -alert_id = "test_url_param" -response = sg.client.alerts._(alert_id).delete() -print response.status_code -print response.body -print response.headers - - -API KEYS - -Create API keys - -This endpoint allows you to create a new random API Key for the user. - -A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. - -There is a limit of 100 API Keys on your account. - -The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. - -See the API Key Permissions List for a list of all available scopes. - -POST /api_keys - - -data = { - "name": "My API Key", - "sample": "data", - "scopes": [ -​ "mail.send", -​ "alerts.create", -​ "alerts.read" - ] -} -response = sg.client.api_keys.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all API Keys belonging to the authenticated user - -This endpoint allows you to retrieve all API Keys that belong to the authenticated user. - -The API Keys feature allows customers to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. - -GET /api_keys - - -params = {'limit': 1} -response = sg.client.api_keys.get(query_params=params) -print response.status_code -print response.body -print response.headers -Update the name & scopes of an API Key - -This endpoint allows you to update the name and scopes of a given API key. - -A JSON request body with a "name" property is required. -Most provide the list of all the scopes an api key should have. - -The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. - -PUT /api_keys/{api_key_id} - - -data = { - "name": "A New Hope", - "scopes": [ -​ "user.profile.read", -​ "user.profile.update" - ] -} -api_key_id = "test_url_param" -response = sg.client.api_keys._(api_key_id).put(request_body=data) -print response.status_code -print response.body -print response.headers -Update API keys - -This endpoint allows you to update the name of an existing API Key. - -A JSON request body with a "name" property is required. - -The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. - -URI Parameters - -URI PARAMETER TYPE REQUIRED? DESCRIPTION -api_key_id string required The ID of the API Key you are updating. -PATCH /api_keys/{api_key_id} - - -data = { - "name": "A New Hope" -} -api_key_id = "test_url_param" -response = sg.client.api_keys._(api_key_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve an existing API Key - -This endpoint allows you to retrieve a single API key. - -If the API Key ID does not exist an HTTP 404 will be returned. - -GET /api_keys/{api_key_id} - - -api_key_id = "test_url_param" -response = sg.client.api_keys._(api_key_id).get() -print response.status_code -print response.body -print response.headers -Delete API keys - -This endpoint allows you to revoke an existing API Key. - -Authentications using this API Key will fail after this request is made, with some small propagation delay.If the API Key ID does not exist an HTTP 404 will be returned. - -The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the Mail API Endpoint. - -URI Parameters - -URI PARAMETER TYPE REQUIRED? DESCRIPTION -api_key_id string required The ID of the API Key you are deleting. -DELETE /api_keys/{api_key_id} - - -api_key_id = "test_url_param" -response = sg.client.api_keys._(api_key_id).delete() -print response.status_code -print response.body -print response.headers - - -ASM - -Create a new suppression group - -This endpoint allows you to create a new suppression group. - -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - -The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. - -Each user can create up to 25 different suppression groups. - -POST /asm/groups - - -data = { - "description": "Suggestions for products our users might like.", - "is_default": True, - "name": "Product Suggestions" -} -response = sg.client.asm.groups.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve information about multiple suppression groups - -This endpoint allows you to retrieve information about multiple suppression groups. - -This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append &id= followed by the group ID. - -Suppressions are a list of email addresses that will not receive content sent under a given group. - -Suppression groups, or unsubscribe groups, allow you to label a category of content that you regularly send. This gives your recipients the ability to opt out of a specific set of your email. For example, you might define a group for your transactional email, and one for your marketing email so that your users can continue receiving your transactional email without having to receive your marketing content. - -GET /asm/groups - - -params = {'id': 1} -response = sg.client.asm.groups.get(query_params=params) -print response.status_code -print response.body -print response.headers -Update a suppression group. - -This endpoint allows you to update or change a suppression group. - -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - -The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. - -Each user can create up to 25 different suppression groups. - -PATCH /asm/groups/{group_id} - - -data = { - "description": "Suggestions for items our users might like.", - "id": 103, - "name": "Item Suggestions" -} -group_id = "test_url_param" -response = sg.client.asm.groups._(group_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Get information on a single suppression group. - -This endpoint allows you to retrieve a single suppression group. - -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - -The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. - -Each user can create up to 25 different suppression groups. - -GET /asm/groups/{group_id} - - -group_id = "test_url_param" -response = sg.client.asm.groups._(group_id).get() -print response.status_code -print response.body -print response.headers -Delete a suppression group. - -This endpoint allows you to delete a suppression group. - -You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list. - -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. - -The name and description of the unsubscribe group will be visible by recipients when they are managing their subscriptions. - -Each user can create up to 25 different suppression groups. - -DELETE /asm/groups/{group_id} - - -group_id = "test_url_param" -response = sg.client.asm.groups._(group_id).delete() -print response.status_code -print response.body -print response.headers -Add suppressions to a suppression group - -This endpoint allows you to add email addresses to an unsubscribe group. - -If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list. - -Suppressions are recipient email addresses that are added to unsubscribe groups. Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. - -POST /asm/groups/{group_id}/suppressions - - -data = { - "recipient_emails": [ -​ "test1@example.com", -​ "test2@example.com" - ] -} -group_id = "test_url_param" -response = sg.client.asm.groups._(group_id).suppressions.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all suppressions for a suppression group - -This endpoint allows you to retrieve all suppressed email addresses belonging to the given group. - -Suppressions are recipient email addresses that are added to unsubscribe groups. Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. - -GET /asm/groups/{group_id}/suppressions - - -group_id = "test_url_param" -response = sg.client.asm.groups._(group_id).suppressions.get() -print response.status_code -print response.body -print response.headers -Search for suppressions within a group - -This endpoint allows you to search a suppression group for multiple suppressions. - -When given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group. - -Suppressions are a list of email addresses that will not receive content sent under a given group. - -POST /asm/groups/{group_id}/suppressions/search - - -data = { - "recipient_emails": [ -​ "exists1@example.com", -​ "exists2@example.com", -​ "doesnotexists@example.com" - ] -} -group_id = "test_url_param" -response = sg.client.asm.groups._(group_id).suppressions.search.post(request_body=data) -print response.status_code -print response.body -print response.headers -Delete a suppression from a suppression group - -This endpoint allows you to remove a suppressed email address from the given suppression group. - -Suppressions are recipient email addresses that are added to unsubscribe groups. Once a recipient's address is on the suppressions list for an unsubscribe group, they will not receive any emails that are tagged with that unsubscribe group. - -DELETE /asm/groups/{group_id}/suppressions/{email} - - -group_id = "test_url_param" -email = "test_url_param" -response = sg.client.asm.groups._(group_id).suppressions._(email).delete() -print response.status_code -print response.body -print response.headers -Retrieve all suppressions - -This endpoint allows you to retrieve a list of all suppressions. - -Suppressions are a list of email addresses that will not receive content sent under a given group. - -GET /asm/suppressions - - -response = sg.client.asm.suppressions.get() -print response.status_code -print response.body -print response.headers -Add recipient addresses to the global suppression group. - -This endpoint allows you to add one or more email addresses to the global suppressions group. - -A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. - -POST /asm/suppressions/global - - -data = { - "recipient_emails": [ -​ "test1@example.com", -​ "test2@example.com" - ] -} -response = sg.client.asm.suppressions._("global").post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a Global Suppression - -This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email address is already globally suppressed. - -If the email address you include in the URL path parameter {email} is already globally suppressed, the response will include that email address. If the address you enter for {email} is not globally suppressed, an empty JSON object {} will be returned. - -A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. - -GET /asm/suppressions/global/{email} - - -email = "test_url_param" -response = sg.client.asm.suppressions._("global")._(email).get() -print response.status_code -print response.body -print response.headers -Delete a Global Suppression - -This endpoint allows you to remove an email address from the global suppressions group. - -A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. - -DELETE /asm/suppressions/global/{email} - - -email = "test_url_param" -response = sg.client.asm.suppressions._("global")._(email).delete() -print response.status_code -print response.body -print response.headers -Retrieve all suppression groups for an email address - -This endpoint returns the list of all groups that the given email address has been unsubscribed from. - -Suppressions are a list of email addresses that will not receive content sent under a given group. - -GET /asm/suppressions/{email} - - -email = "test_url_param" -response = sg.client.asm.suppressions._(email).get() -print response.status_code -print response.body -print response.headers - - -BROWSERS - -Retrieve email statistics by browser. - -This endpoint allows you to retrieve your email statistics segmented by browser type. - -We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. - -Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. - -GET /browsers/stats - - -params = {'end_date': '2016-04-01', 'aggregated_by': 'day', 'browsers': 'test_string', 'limit': 'test_string', 'offset': 'test_string', 'start_date': '2016-01-01'} -response = sg.client.browsers.stats.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -CAMPAIGNS - -Create a Campaign - -This endpoint allows you to create a campaign. - -Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - -Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. - -For more information: - -User Guide > Marketing Campaigns - -POST /campaigns - - -data = { - "categories": [ -​ "spring line" - ], - "custom_unsubscribe_url": "", - "html_content": "

Check out our spring line!

", - "ip_pool": "marketing", - "list_ids": [ -​ 110, -​ 124 - ], - "plain_content": "Check out our spring line!", - "segment_ids": [ -​ 110 - ], - "sender_id": 124451, - "subject": "New Products for Spring!", - "suppression_group_id": 42, - "title": "March Newsletter" -} -response = sg.client.campaigns.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all Campaigns - -This endpoint allows you to retrieve a list of all of your campaigns. - -Returns campaigns in reverse order they were created (newest first). - -Returns an empty array if no campaigns exist. - -For more information: - -User Guide > Marketing Campaigns - -GET /campaigns - - -params = {'limit': 10, 'offset': 0} -response = sg.client.campaigns.get(query_params=params) -print response.status_code -print response.body -print response.headers -Update a Campaign - -Update a campaign. This is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters. - -For more information: - -User Guide > Marketing Campaigns - -PATCH /campaigns/{campaign_id} - - -data = { - "categories": [ -​ "summer line" - ], - "html_content": "

Check out our summer line!

", - "plain_content": "Check out our summer line!", - "subject": "New Products for Summer!", - "title": "May Newsletter" -} -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a single campaign - -This endpoint allows you to retrieve a specific campaign. - -Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - -For more information: - -User Guide > Marketing Campaigns - -GET /campaigns/{campaign_id} - - -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).get() -print response.status_code -print response.body -print response.headers -Delete a Campaign - -This endpoint allows you to delete a specific campaign. - -Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. - -For more information: - -User Guide > Marketing Campaigns - -DELETE /campaigns/{campaign_id} - - -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).delete() -print response.status_code -print response.body -print response.headers -Update a Scheduled Campaign - -This endpoint allows to you change the scheduled time and date for a campaign to be sent. - -For more information: - -User Guide > Marketing Campaigns - -PATCH /campaigns/{campaign_id}/schedules - - -data = { - "send_at": 1489451436 -} -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).schedules.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Schedule a Campaign - -This endpoint allows you to schedule a specific date and time for your campaign to be sent. - -For more information: - -User Guide > Marketing Campaigns - -POST /campaigns/{campaign_id}/schedules - - -data = { - "send_at": 1489771528 -} -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).schedules.post(request_body=data) -print response.status_code -print response.body -print response.headers -View Scheduled Time of a Campaign - -This endpoint allows you to retrieve the date and time that the given campaign has been scheduled to be sent. - -For more information: - -User Guide > Marketing Campaigns - -GET /campaigns/{campaign_id}/schedules - - -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).schedules.get() -print response.status_code -print response.body -print response.headers -Unschedule a Scheduled Campaign - -This endpoint allows you to unschedule a campaign that has already been scheduled to be sent. - -A successful unschedule will return a 204. -If the specified campaign is in the process of being sent, the only option is to cancel (a different method). - -For more information: - -User Guide > Marketing Campaigns - -DELETE /campaigns/{campaign_id}/schedules - - -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).schedules.delete() -print response.status_code -print response.body -print response.headers -Send a Campaign - -This endpoint allows you to immediately send a campaign at the time you make the API call. - -Normally a POST would have a request body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed. - -For more information: - -User Guide > Marketing Campaigns - -POST /campaigns/{campaign_id}/schedules/now - - -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).schedules.now.post() -print response.status_code -print response.body -print response.headers -Send a Test Campaign - -This endpoint allows you to send a test campaign. - -To send to multiple addresses, use an array for the JSON "to" value ["one@address","two@address"] - -For more information: - -User Guide > Marketing Campaigns - -POST /campaigns/{campaign_id}/schedules/test - - -data = { - "to": "your.email@example.com" -} -campaign_id = "test_url_param" -response = sg.client.campaigns._(campaign_id).schedules.test.post(request_body=data) -print response.status_code -print response.body -print response.headers - - -CATEGORIES - -Retrieve all categories - -This endpoint allows you to retrieve a list of all of your categories. - -Categories can help organize your email analytics by enabling you to tag emails by type or broad topic. You can define your own custom categories. For more information, please see our User Guide. - -GET /categories - - -params = {'category': 'test_string', 'limit': 1, 'offset': 1} -response = sg.client.categories.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve Email Statistics for Categories - -This endpoint allows you to retrieve all of your email statistics for each of your categories. - -If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - -Categories allow you to group your emails together according to broad topics that you define. For more information, please see our User Guide. - -GET /categories/stats - - -params = {'end_date': '2016-04-01', 'aggregated_by': 'day', 'limit': 1, 'offset': 1, 'start_date': '2016-01-01', 'categories': 'test_string'} -response = sg.client.categories.stats.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?] - -This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range. - -If you do not define any query parameters, this endpoint will return a sum for each category in groups of 10. - -Categories allow you to group your emails together according to broad topics that you define. For more information, please see our User Guide. - -GET /categories/stats/sums - - -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.categories.stats.sums.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -CLIENTS - -Retrieve email statistics by client type. - -This endpoint allows you to retrieve your email statistics segmented by client type. - -We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. - -Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. - -GET /clients/stats - - -params = {'aggregated_by': 'day', 'start_date': '2016-01-01', 'end_date': '2016-04-01'} -response = sg.client.clients.stats.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve stats by a specific client type. - -This endpoint allows you to retrieve your email statistics segmented by a specific client type. - -We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. - -Available Client Types - -phone - -tablet - -webmail - -desktop - -Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. - -GET /clients/{client_type}/stats - - -params = {'aggregated_by': 'day', 'start_date': '2016-01-01', 'end_date': '2016-04-01'} -client_type = "test_url_param" -response = sg.client.clients._(client_type).stats.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -CONTACTDB - -Create a Custom Field - -This endpoint allows you to create a custom field. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -POST /contactdb/custom_fields - - -data = { - "name": "pet", - "type": "text" -} -response = sg.client.contactdb.custom_fields.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all custom fields - -This endpoint allows you to retrieve all custom fields. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -GET /contactdb/custom_fields - - -response = sg.client.contactdb.custom_fields.get() -print response.status_code -print response.body -print response.headers -Retrieve a Custom Field - -This endpoint allows you to retrieve a custom field by ID. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -GET /contactdb/custom_fields/{custom_field_id} - - -custom_field_id = "test_url_param" -response = sg.client.contactdb.custom_fields._(custom_field_id).get() -print response.status_code -print response.body -print response.headers -Delete a Custom Field - -This endpoint allows you to delete a custom field by ID. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -DELETE /contactdb/custom_fields/{custom_field_id} - - -custom_field_id = "test_url_param" -response = sg.client.contactdb.custom_fields._(custom_field_id).delete() -print response.status_code -print response.body -print response.headers -Create a List - -This endpoint allows you to create a list for your recipients. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -POST /contactdb/lists - - -data = { - "name": "your list name" -} -response = sg.client.contactdb.lists.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all lists - -This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will be returned. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -GET /contactdb/lists - - -response = sg.client.contactdb.lists.get() -print response.status_code -print response.body -print response.headers -Delete Multiple lists - -This endpoint allows you to delete multiple recipient lists. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -DELETE /contactdb/lists - - -data = [ - 1, - 2, - 3, - 4 -] -response = sg.client.contactdb.lists.delete(request_body=data) -print response.status_code -print response.body -print response.headers -Update a List - -This endpoint allows you to update the name of one of your recipient lists. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -PATCH /contactdb/lists/{list_id} - - -data = { - "name": "newlistname" -} -params = {'list_id': 1} -list_id = "test_url_param" -response = sg.client.contactdb.lists._(list_id).patch(request_body=data, query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve a single list - -This endpoint allows you to retrieve a single recipient list. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -GET /contactdb/lists/{list_id} - - -params = {'list_id': 1} -list_id = "test_url_param" -response = sg.client.contactdb.lists._(list_id).get(query_params=params) -print response.status_code -print response.body -print response.headers -Delete a List - -This endpoint allows you to delete a specific recipient list with the given ID. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -DELETE /contactdb/lists/{list_id} - - -params = {'delete_contacts': 'true'} -list_id = "test_url_param" -response = sg.client.contactdb.lists._(list_id).delete(query_params=params) -print response.status_code -print response.body -print response.headers -Add Multiple Recipients to a List - -This endpoint allows you to add multiple recipients to a list. - -Adds existing recipients to a list, passing in the recipient IDs to add. Recipient IDs should be passed exactly as they are returned from recipient endpoints. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -POST /contactdb/lists/{list_id}/recipients - - -data = [ - "recipient_id1", - "recipient_id2" -] -list_id = "test_url_param" -response = sg.client.contactdb.lists._(list_id).recipients.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all recipients on a List - -This endpoint allows you to retrieve all recipients on the list with the given ID. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -GET /contactdb/lists/{list_id}/recipients - - -params = {'page': 1, 'page_size': 1, 'list_id': 1} -list_id = "test_url_param" -response = sg.client.contactdb.lists._(list_id).recipients.get(query_params=params) -print response.status_code -print response.body -print response.headers -Add a Single Recipient to a List - -This endpoint allows you to add a single recipient to a list. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -POST /contactdb/lists/{list_id}/recipients/{recipient_id} - - -list_id = "test_url_param" -recipient_id = "test_url_param" -response = sg.client.contactdb.lists._(list_id).recipients._(recipient_id).post() -print response.status_code -print response.body -print response.headers -Delete a Single Recipient from a Single List - -This endpoint allows you to delete a single recipient from a list. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -DELETE /contactdb/lists/{list_id}/recipients/{recipient_id} - - -params = {'recipient_id': 1, 'list_id': 1} -list_id = "test_url_param" -recipient_id = "test_url_param" -response = sg.client.contactdb.lists._(list_id).recipients._(recipient_id).delete(query_params=params) -print response.status_code -print response.body -print response.headers -Update Recipient - -This endpoint allows you to update one or more recipients. - -The body of an API call to this endpoint must include an array of one or more recipient objects. - -It is of note that you can add custom field data as parameters on recipient objects. We have provided an example using some of the default custom fields SendGrid provides. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -PATCH /contactdb/recipients - - -data = [ - { -​ "email": "jones@example.com", -​ "first_name": "Guy", -​ "last_name": "Jones" - } -] -response = sg.client.contactdb.recipients.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Add recipients - -This endpoint allows you to add a Marketing Campaigns recipient. - -It is of note that you can add custom field data as a parameter on this endpoint. We have provided an example using some of the default custom fields SendGrid provides. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -POST /contactdb/recipients - - -data = [ - { -​ "age": 25, -​ "email": "example@example.com", -​ "first_name": "", -​ "last_name": "User" - }, - { -​ "age": 25, -​ "email": "example2@example.com", -​ "first_name": "Example", -​ "last_name": "User" - } -] -response = sg.client.contactdb.recipients.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve recipients - -This endpoint allows you to retrieve all of your Marketing Campaigns recipients. - -Batch deletion of a page makes it possible to receive an empty page of recipients before reaching the end of -the list of recipients. To avoid this issue; iterate over pages until a 404 is retrieved. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -GET /contactdb/recipients - - -params = {'page': 1, 'page_size': 1} -response = sg.client.contactdb.recipients.get(query_params=params) -print response.status_code -print response.body -print response.headers -Delete Recipient - -This endpoint allows you to deletes one or more recipients. - -The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -DELETE /contactdb/recipients - - -data = [ - "recipient_id1", - "recipient_id2" -] -response = sg.client.contactdb.recipients.delete(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve the count of billable recipients - -This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for. - -You are billed for marketing campaigns based on the highest number of recipients you have had in your account at one time. This endpoint will allow you to know the current billable count value. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -GET /contactdb/recipients/billable_count - - -response = sg.client.contactdb.recipients.billable_count.get() -print response.status_code -print response.body -print response.headers -Retrieve a Count of Recipients - -This endpoint allows you to retrieve the total number of Marketing Campaigns recipients. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -GET /contactdb/recipients/count - - -response = sg.client.contactdb.recipients.count.get() -print response.status_code -print response.body -print response.headers -Retrieve recipients matching search criteria - -This endpoint allows you to perform a search on all of your Marketing Campaigns recipients. - -field_name: - -is a variable that is substituted for your actual custom field name from your recipient. - -Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) - -If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert -your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to -Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through -Mon, 02 Feb 2015 23:59:59 GMT. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -GET /contactdb/recipients/search - - -params = {'{field_name}': 'test_string'} -response = sg.client.contactdb.recipients.search.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve a single recipient - -This endpoint allows you to retrieve a single recipient by ID from your contact database. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -GET /contactdb/recipients/{recipient_id} - - -recipient_id = "test_url_param" -response = sg.client.contactdb.recipients._(recipient_id).get() -print response.status_code -print response.body -print response.headers -Delete a Recipient - -This endpoint allows you to delete a single recipient with the given ID from your contact database. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -DELETE /contactdb/recipients/{recipient_id} - - -recipient_id = "test_url_param" -response = sg.client.contactdb.recipients._(recipient_id).delete() -print response.status_code -print response.body -print response.headers -Retrieve the lists that a recipient is on - -This endpoint allows you to retrieve the lists that a given recipient belongs to. - -Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -GET /contactdb/recipients/{recipient_id}/lists - - -recipient_id = "test_url_param" -response = sg.client.contactdb.recipients._(recipient_id).lists.get() -print response.status_code -print response.body -print response.headers -Retrieve reserved fields - -This endpoint allows you to list all fields that are reserved and can't be used for custom field names. - -The contactdb is a database of your contacts for SendGrid Marketing Campaigns. - -GET /contactdb/reserved_fields - - -response = sg.client.contactdb.reserved_fields.get() -print response.status_code -print response.body -print response.headers -Create a Segment - -This endpoint allows you to create a segment. - -All recipients in your contactdb will be added or removed automatically depending on whether they match the criteria for this segment. - -List Id: - -Send this to segment from an existing list - -Don't send this in order to segment from your entire contactdb. - -Valid operators for create and update depend on the type of the field you are segmenting: - -Dates: "eq", "ne", "lt" (before), "gt" (after) - -Text: "contains", "eq" (is - matches the full field), "ne" (is not - matches any field where the entire field is not the condition value) - -Numbers: "eq", "lt", "gt" - -Email Clicks and Opens: "eq" (opened), "ne" (not opened) - -Segment conditions using "eq" or "ne" for email clicks and opens should provide a "field" of either clicks.campaign_identifier or opens.campaign_identifier. The condition value should be a string containing the id of a completed campaign. - -Segments may contain multiple conditions, joined by an "and" or "or" in the "and_or" field. The first condition in the conditions list must have an empty "and_or", and subsequent conditions must all specify an "and_or". - -The Contacts API helps you manage your Marketing Campaigns recipients. - -For more information about segments in Marketing Campaigns, please see our User Guide. - -POST /contactdb/segments - - -data = { - "conditions": [ -​ { -​ "and_or": "", -​ "field": "last_name", -​ "operator": "eq", -​ "value": "Miller" -​ }, -​ { -​ "and_or": "and", -​ "field": "last_clicked", -​ "operator": "gt", -​ "value": "01/02/2015" -​ }, -​ { -​ "and_or": "or", -​ "field": "clicks.campaign_identifier", -​ "operator": "eq", -​ "value": "513" -​ } - ], - "list_id": 4, - "name": "Last Name Miller" -} -response = sg.client.contactdb.segments.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all segments - -This endpoint allows you to retrieve all of your segments. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -For more information about segments in Marketing Campaigns, please see our User Guide. - -GET /contactdb/segments - - -response = sg.client.contactdb.segments.get() -print response.status_code -print response.body -print response.headers -Update a segment - -This endpoint allows you to update a segment. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -For more information about segments in Marketing Campaigns, please see our User Guide. - -PATCH /contactdb/segments/{segment_id} - - -data = { - "conditions": [ -​ { -​ "and_or": "", -​ "field": "last_name", -​ "operator": "eq", -​ "value": "Miller" -​ } - ], - "list_id": 5, - "name": "The Millers" -} -params = {'segment_id': 'test_string'} -segment_id = "test_url_param" -response = sg.client.contactdb.segments._(segment_id).patch(request_body=data, query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve a segment - -This endpoint allows you to retrieve a single segment with the given ID. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -For more information about segments in Marketing Campaigns, please see our User Guide. - -GET /contactdb/segments/{segment_id} - - -params = {'segment_id': 1} -segment_id = "test_url_param" -response = sg.client.contactdb.segments._(segment_id).get(query_params=params) -print response.status_code -print response.body -print response.headers -Delete a segment - -This endpoint allows you to delete a segment from your recipients database. - -You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -For more information about segments in Marketing Campaigns, please see our User Guide. - -DELETE /contactdb/segments/{segment_id} - - -params = {'delete_contacts': 'true'} -segment_id = "test_url_param" -response = sg.client.contactdb.segments._(segment_id).delete(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve recipients on a segment - -This endpoint allows you to retrieve all of the recipients in a segment with the given ID. - -The Contacts API helps you manage your Marketing Campaigns recipients. - -For more information about segments in Marketing Campaigns, please see our User Guide. - -GET /contactdb/segments/{segment_id}/recipients - - -params = {'page': 1, 'page_size': 1} -segment_id = "test_url_param" -response = sg.client.contactdb.segments._(segment_id).recipients.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -DEVICES - -Retrieve email statistics by device type. - -This endpoint allows you to retrieve your email statistics segmented by the device type. - -We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. - -Available Device Types - -DEVICE DESCRIPTION EXAMPLE -Desktop Email software on desktop computer. I.E., Outlook, Sparrow, or Apple Mail. -Webmail A web-based email client. I.E., Yahoo, Google, AOL, or Outlook.com. -| Phone | A smart phone. | iPhone, Android, Blackberry, etc. -| Tablet | A tablet computer. | iPad, android based tablet, etc. | -| Other | An unrecognized device. | - -Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. - -GET /devices/stats - - -params = {'aggregated_by': 'day', 'limit': 1, 'start_date': '2016-01-01', 'end_date': '2016-04-01', 'offset': 1} -response = sg.client.devices.stats.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -GEO - -Retrieve email statistics by country and state/province. - -This endpoint allows you to retrieve your email statistics segmented by country and state/province. - -We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. - -Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. - -GET /geo/stats - - -params = {'end_date': '2016-04-01', 'country': 'US', 'aggregated_by': 'day', 'limit': 1, 'offset': 1, 'start_date': '2016-01-01'} -response = sg.client.geo.stats.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -IPS - -Retrieve all IP addresses - -This endpoint allows you to retrieve a list of all assigned and unassigned IPs. - -Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. - -A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - -GET /ips - - -params = {'subuser': 'test_string', 'ip': 'test_string', 'limit': 1, 'exclude_whitelabels': 'true', 'offset': 1} -response = sg.client.ips.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve all assigned IPs - -This endpoint allows you to retrieve only assigned IP addresses. - -A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - -GET /ips/assigned - - -response = sg.client.ips.assigned.get() -print response.status_code -print response.body -print response.headers -Create an IP pool. - -This endpoint allows you to create an IP pool. - -Each user can create up to 10 different IP pools. - -IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - -IP pools can only be used with whitelabeled IP addresses. - -If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - -POST /ips/pools - - -data = { - "name": "marketing" -} -response = sg.client.ips.pools.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all IP pools. - -This endpoint allows you to retrieve all of your IP pools. - -IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - -IP pools can only be used with whitelabeled IP addresses. - -If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - -GET /ips/pools - - -response = sg.client.ips.pools.get() -print response.status_code -print response.body -print response.headers -Update an IP pools name. - -This endpoint allows you to update the name of an IP pool. - -IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - -IP pools can only be used with whitelabeled IP addresses. - -If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - -PUT /ips/pools/{pool_name} - - -data = { - "name": "new_pool_name" -} -pool_name = "test_url_param" -response = sg.client.ips.pools._(pool_name).put(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all IPs in a specified pool. - -This endpoint allows you to list all of the IP addresses that are in a specific IP pool. - -IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - -IP pools can only be used with whitelabeled IP addresses. - -If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - -GET /ips/pools/{pool_name} - - -pool_name = "test_url_param" -response = sg.client.ips.pools._(pool_name).get() -print response.status_code -print response.body -print response.headers -Delete an IP pool. - -This endpoint allows you to delete an IP pool. - -IP Pools allow you to group your dedicated SendGrid IP addresses together. For example, you could create separate pools for your transactional and marketing email. When sending marketing emails, specify that you want to use the marketing IP pool. This allows you to maintain separate reputations for your different email traffic. - -IP pools can only be used with whitelabeled IP addresses. - -If an IP pool is NOT specified for an email, it will use any IP available, including ones in pools. - -DELETE /ips/pools/{pool_name} - - -pool_name = "test_url_param" -response = sg.client.ips.pools._(pool_name).delete() -print response.status_code -print response.body -print response.headers -Add an IP address to a pool - -This endpoint allows you to add an IP address to an IP pool. - -You can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made. - -A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - -POST /ips/pools/{pool_name}/ips - - -data = { - "ip": "0.0.0.0" -} -pool_name = "test_url_param" -response = sg.client.ips.pools._(pool_name).ips.post(request_body=data) -print response.status_code -print response.body -print response.headers -Remove an IP address from a pool. - -This endpoint allows you to remove an IP address from an IP pool. - -The same IP address can be added to multiple IP pools. - -A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - -DELETE /ips/pools/{pool_name}/ips/{ip} - - -pool_name = "test_url_param" -ip = "test_url_param" -response = sg.client.ips.pools._(pool_name).ips._(ip).delete() -print response.status_code -print response.body -print response.headers -Add an IP to warmup - -This endpoint allows you to enter an IP address into warmup mode. - -SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. - -For more general information about warming up IPs, please see our Classroom. - -POST /ips/warmup - - -data = { - "ip": "0.0.0.0" -} -response = sg.client.ips.warmup.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all IPs currently in warmup - -This endpoint allows you to retrieve all of your IP addresses that are currently warming up. - -SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. - -For more general information about warming up IPs, please see our Classroom. - -GET /ips/warmup - - -response = sg.client.ips.warmup.get() -print response.status_code -print response.body -print response.headers -Retrieve warmup status for a specific IP address - -This endpoint allows you to retrieve the warmup status for a specific IP address. - -SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. - -For more general information about warming up IPs, please see our Classroom. - -GET /ips/warmup/{ip_address} - - -ip_address = "test_url_param" -response = sg.client.ips.warmup._(ip_address).get() -print response.status_code -print response.body -print response.headers -Remove an IP from warmup - -This endpoint allows you to remove an IP address from warmup mode. - -SendGrid can automatically warm up dedicated IP addresses by limiting the amount of mail that can be sent through them per hour, with the limit determined by how long the IP address has been in warmup. See the warmup schedule for more details on how SendGrid limits your email traffic for IPs in warmup. - -For more general information about warming up IPs, please see our Classroom. - -DELETE /ips/warmup/{ip_address} - - -ip_address = "test_url_param" -response = sg.client.ips.warmup._(ip_address).delete() -print response.status_code -print response.body -print response.headers -Retrieve all IP pools an IP address belongs to - -This endpoint allows you to see which IP pools a particular IP address has been added to. - -The same IP address can be added to multiple IP pools. - -A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. - -GET /ips/{ip_address} - - -ip_address = "test_url_param" -response = sg.client.ips._(ip_address).get() -print response.status_code -print response.body -print response.headers - - -MAIL - -Create a batch ID - -This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint. - -If you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. - -More Information: - -Scheduling Parameters > Batch ID - -POST /mail/batch - - -response = sg.client.mail.batch.post() -print response.status_code -print response.body -print response.headers -Validate batch ID - -This endpoint allows you to validate a batch ID. - -If you set the SMTPAPI header batch_id, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. - -More Information: - -Scheduling Parameters > Batch ID - -GET /mail/batch/{batch_id} - - -batch_id = "test_url_param" -response = sg.client.mail.batch._(batch_id).get() -print response.status_code -print response.body -print response.headers -v3 Mail Send - -This endpoint allows you to send email over SendGrids v3 Web API, the most recent version of our API. If you are looking for documentation about the v2 Mail Send endpoint, please see our v2 API Reference. - -Top level parameters are referred to as "global". - -Individual fields within the personalizations array will override any other global, or message level, parameters that are defined outside of personalizations. - -For an overview of the v3 Mail Send endpoint, please visit our v3 API Reference - -For more detailed information about how to use the v3 Mail Send endpoint, please visit our Classroom. - -POST /mail/send - -This endpoint has a helper, check it out here. - - -data = { - "asm": { -​ "group_id": 1, -​ "groups_to_display": [ -​ 1, -​ 2, -​ 3 -​ ] - }, - "attachments": [ -​ { -​ "content": "[BASE64 encoded content block here]", -​ "content_id": "ii_139db99fdb5c3704", -​ "disposition": "inline", -​ "filename": "file1.jpg", -​ "name": "file1", -​ "type": "jpg" -​ } - ], - "batch_id": "[YOUR BATCH ID GOES HERE]", - "categories": [ -​ "category1", -​ "category2" - ], - "content": [ -​ { -​ "type": "text/html", -​ "value": "

Hello, world!

" -​ } - ], - "custom_args": { -​ "New Argument 1": "New Value 1", -​ "activationAttempt": "1", -​ "customerAccountNumber": "[CUSTOMER ACCOUNT NUMBER GOES HERE]" - }, - "from": { -​ "email": "sam.smith@example.com", -​ "name": "Sam Smith" - }, - "headers": {}, - "ip_pool_name": "[YOUR POOL NAME GOES HERE]", - "mail_settings": { -​ "bcc": { -​ "email": "ben.doe@example.com", -​ "enable": True -​ }, -​ "bypass_list_management": { -​ "enable": True -​ }, -​ "footer": { -​ "enable": True, -​ "html": "

Thanks
The SendGrid Team

", -​ "text": "Thanks,/n The SendGrid Team" -​ }, -​ "sandbox_mode": { -​ "enable": False -​ }, -​ "spam_check": { -​ "enable": True, -​ "post_to_url": "http://example.com/compliance", -​ "threshold": 3 -​ } - }, - "personalizations": [ -​ { -​ "bcc": [ -​ { -​ "email": "sam.doe@example.com", -​ "name": "Sam Doe" -​ } -​ ], -​ "cc": [ -​ { -​ "email": "jane.doe@example.com", -​ "name": "Jane Doe" -​ } -​ ], -​ "custom_args": { -​ "New Argument 1": "New Value 1", -​ "activationAttempt": "1", -​ "customerAccountNumber": "[CUSTOMER ACCOUNT NUMBER GOES HERE]" -​ }, -​ "headers": { -​ "X-Accept-Language": "en", -​ "X-Mailer": "MyApp" -​ }, -​ "send_at": 1409348513, -​ "subject": "Hello, World!", -​ "substitutions": { -​ "id": "substitutions", -​ "type": "object" -​ }, -​ "to": [ -​ { -​ "email": "john.doe@example.com", -​ "name": "John Doe" -​ } -​ ] -​ } - ], - "reply_to": { -​ "email": "sam.smith@example.com", -​ "name": "Sam Smith" - }, - "sections": { -​ "section": { -​ ":sectionName1": "section 1 text", -​ ":sectionName2": "section 2 text" -​ } - }, - "send_at": 1409348513, - "subject": "Hello, World!", - "template_id": "[YOUR TEMPLATE ID GOES HERE]", - "tracking_settings": { -​ "click_tracking": { -​ "enable": True, -​ "enable_text": True -​ }, -​ "ganalytics": { -​ "enable": True, -​ "utm_campaign": "[NAME OF YOUR REFERRER SOURCE]", -​ "utm_content": "[USE THIS SPACE TO DIFFERENTIATE YOUR EMAIL FROM ADS]", -​ "utm_medium": "[NAME OF YOUR MARKETING MEDIUM e.g. email]", -​ "utm_name": "[NAME OF YOUR CAMPAIGN]", -​ "utm_term": "[IDENTIFY PAID KEYWORDS HERE]" -​ }, -​ "open_tracking": { -​ "enable": True, -​ "substitution_tag": "%opentrack" -​ }, -​ "subscription_tracking": { -​ "enable": True, -​ "html": "If you would like to unsubscribe and stop receiving these emails <% clickhere %>.", -​ "substitution_tag": "<%click here%>", -​ "text": "If you would like to unsubscribe and stop receiving these emails <% click here %>." -​ } - } -} -response = sg.client.mail.send.post(request_body=data) -print response.status_code -print response.body -print response.headers - - -MAIL SETTINGS - -Retrieve all mail settings - -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 or SMTP Relay. - -GET /mail_settings - - -params = {'limit': 1, 'offset': 1} -response = sg.client.mail_settings.get(query_params=params) -print response.status_code -print response.body -print response.headers -Update address whitelist mail settings - -This endpoint allows you to update your current email address whitelist settings. - -The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -PATCH /mail_settings/address_whitelist - - -data = { - "enabled": True, - "list": [ -​ "email1@example.com", -​ "example.com" - ] -} -response = sg.client.mail_settings.address_whitelist.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve address whitelist mail settings - -This endpoint allows you to retrieve your current email address whitelist settings. - -The address whitelist setting whitelists a specified email address or domain for which mail should never be suppressed. For example, you own the domain example.com, and one or more of your recipients use email@example.com addresses, by placing example.com in the address whitelist setting, all bounces, blocks, and unsubscribes logged for that domain will be ignored and sent as if under normal sending conditions. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -GET /mail_settings/address_whitelist - - -response = sg.client.mail_settings.address_whitelist.get() -print response.status_code -print response.body -print response.headers -Update BCC mail settings - -This endpoint allows you to update your current BCC mail settings. - -When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -PATCH /mail_settings/bcc - - -data = { - "email": "email@example.com", - "enabled": False -} -response = sg.client.mail_settings.bcc.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all BCC mail settings - -This endpoint allows you to retrieve your current BCC mail settings. - -When the BCC mail setting is enabled, SendGrid will automatically send a blind carbon copy (BCC) to an address for every email sent without adding that address to the header. Please note that only one email address may be entered in this field, if you wish to distribute BCCs to multiple addresses you will need to create a distribution group or use forwarding rules. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -GET /mail_settings/bcc - - -response = sg.client.mail_settings.bcc.get() -print response.status_code -print response.body -print response.headers -Update bounce purge mail settings - -This endpoint allows you to update your current bounce purge settings. - -This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -PATCH /mail_settings/bounce_purge - - -data = { - "enabled": True, - "hard_bounces": 5, - "soft_bounces": 5 -} -response = sg.client.mail_settings.bounce_purge.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve bounce purge mail settings - -This endpoint allows you to retrieve your current bounce purge settings. - -This setting allows you to set a schedule for SendGrid to automatically delete contacts from your soft and hard bounce suppression lists. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -GET /mail_settings/bounce_purge - - -response = sg.client.mail_settings.bounce_purge.get() -print response.status_code -print response.body -print response.headers -Update footer mail settings - -This endpoint allows you to update your current Footer mail settings. - -The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -PATCH /mail_settings/footer - - -data = { - "enabled": True, - "html_content": "...", - "plain_content": "..." -} -response = sg.client.mail_settings.footer.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve footer mail settings - -This endpoint allows you to retrieve your current Footer mail settings. - -The footer setting will insert a custom footer at the bottom of the text and HTML bodies. Use the embedded HTML editor and plain text entry fields to create the content of the footers to be inserted into your emails. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -GET /mail_settings/footer - - -response = sg.client.mail_settings.footer.get() -print response.status_code -print response.body -print response.headers -Update forward bounce mail settings - -This endpoint allows you to update your current bounce forwarding mail settings. - -Activating this setting allows you to specify an email address to which bounce reports are forwarded. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -PATCH /mail_settings/forward_bounce - - -data = { - "email": "example@example.com", - "enabled": True -} -response = sg.client.mail_settings.forward_bounce.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve forward bounce mail settings - -This endpoint allows you to retrieve your current bounce forwarding mail settings. - -Activating this setting allows you to specify an email address to which bounce reports are forwarded. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -GET /mail_settings/forward_bounce - - -response = sg.client.mail_settings.forward_bounce.get() -print response.status_code -print response.body -print response.headers -Update forward spam mail settings - -This endpoint allows you to update your current Forward Spam mail settings. - -Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -PATCH /mail_settings/forward_spam - - -data = { - "email": "", - "enabled": False -} -response = sg.client.mail_settings.forward_spam.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve forward spam mail settings - -This endpoint allows you to retrieve your current Forward Spam mail settings. - -Enabling the forward spam setting allows you to specify an email address to which spam reports will be forwarded. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -GET /mail_settings/forward_spam - - -response = sg.client.mail_settings.forward_spam.get() -print response.status_code -print response.body -print response.headers -Update plain content mail settings - -This endpoint allows you to update your current Plain Content mail settings. - -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 or SMTP Relay. - -PATCH /mail_settings/plain_content - - -data = { - "enabled": False -} -response = sg.client.mail_settings.plain_content.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve plain content mail settings - -This endpoint allows you to retrieve your current Plain Content mail settings. - -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 or SMTP Relay. - -GET /mail_settings/plain_content - - -response = sg.client.mail_settings.plain_content.get() -print response.status_code -print response.body -print response.headers -Update spam check mail settings - -This endpoint allows you to update your current spam checker mail settings. - -The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -PATCH /mail_settings/spam_check - - -data = { - "enabled": True, - "max_score": 5, - "url": "url" -} -response = sg.client.mail_settings.spam_check.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve spam check mail settings - -This endpoint allows you to retrieve your current Spam Checker mail settings. - -The spam checker filter notifies you when emails are detected that exceed a predefined spam threshold. - -Mail settings allow you to tell SendGrid specific things to do to every email that you send to your recipients over SendGrids Web API or SMTP Relay. - -GET /mail_settings/spam_check - - -response = sg.client.mail_settings.spam_check.get() -print response.status_code -print response.body -print response.headers -Update template mail settings - -This endpoint allows you to update your current legacy email template settings. - -This setting refers to our original email templates. We currently support more fully featured transactional templates. - -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 or SMTP Relay. - -PATCH /mail_settings/template - - -data = { - "enabled": True, - "html_content": "<% body %>" -} -response = sg.client.mail_settings.template.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve legacy template mail settings - -This endpoint allows you to retrieve your current legacy email template settings. - -This setting refers to our original email templates. We currently support more fully featured transactional templates. - -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 or SMTP Relay. - -GET /mail_settings/template - - -response = sg.client.mail_settings.template.get() -print response.status_code -print response.body -print response.headers - - -MAILBOX PROVIDERS - -Retrieve email statistics by mailbox provider. - -This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider. - -We only store up to 7 days of email activity in our database. By default, 500 items will be returned per request via the Advanced Stats API endpoints. - -Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our User Guide. - -GET /mailbox_providers/stats - - -params = {'end_date': '2016-04-01', 'mailbox_providers': 'test_string', 'aggregated_by': 'day', 'limit': 1, 'offset': 1, 'start_date': '2016-01-01'} -response = sg.client.mailbox_providers.stats.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -PARTNER SETTINGS - -Returns a list of all partner settings. - -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. - -GET /partner_settings - - -params = {'limit': 1, 'offset': 1} -response = sg.client.partner_settings.get(query_params=params) -print response.status_code -print response.body -print response.headers -Updates New Relic partner settings. - -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. - -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. - -PATCH /partner_settings/new_relic - - -data = { - "enable_subuser_statistics": True, - "enabled": True, - "license_key": "" -} -response = sg.client.partner_settings.new_relic.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Returns all New Relic partner settings. - -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. - -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. - -GET /partner_settings/new_relic - - -response = sg.client.partner_settings.new_relic.get() -print response.status_code -print response.body -print response.headers - - -SCOPES - -Retrieve a list of scopes for which this user has access. - -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, or the Mail API Endpoint. 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 or Classroom. - -GET /scopes - - -response = sg.client.scopes.get() -print response.status_code -print response.body -print response.headers - - -SENDERS - -Create a Sender Identity - -This endpoint allows you to create a new sender identity. - -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. - -POST /senders - - -data = { - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "country": "United States", - "from": { -​ "email": "from@example.com", -​ "name": "Example INC" - }, - "nickname": "My Sender ID", - "reply_to": { -​ "email": "replyto@example.com", -​ "name": "Example INC" - }, - "state": "Colorado", - "zip": "80202" -} -response = sg.client.senders.post(request_body=data) -print response.status_code -print response.body -print response.headers -Get all Sender Identities - -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. - -GET /senders - - -response = sg.client.senders.get() -print response.status_code -print response.body -print response.headers -Update a Sender Identity - -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. - -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. - -PATCH /senders/{sender_id} - - -data = { - "address": "123 Elm St.", - "address_2": "Apt. 456", - "city": "Denver", - "country": "United States", - "from": { -​ "email": "from@example.com", -​ "name": "Example INC" - }, - "nickname": "My Sender ID", - "reply_to": { -​ "email": "replyto@example.com", -​ "name": "Example INC" - }, - "state": "Colorado", - "zip": "80202" -} -sender_id = "test_url_param" -response = sg.client.senders._(sender_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -View a Sender Identity - -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. - -GET /senders/{sender_id} - - -sender_id = "test_url_param" -response = sg.client.senders._(sender_id).get() -print response.status_code -print response.body -print response.headers -Delete a Sender Identity - -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. - -DELETE /senders/{sender_id} - - -sender_id = "test_url_param" -response = sg.client.senders._(sender_id).delete() -print response.status_code -print response.body -print response.headers -Resend Sender Identity Verification - -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. - -POST /senders/{sender_id}/resend_verification - - -sender_id = "test_url_param" -response = sg.client.senders._(sender_id).resend_verification.post() -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 - - -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 Subuser - -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 - -Classroom > How do I add more subusers to my account? - -POST /subusers - - -data = { - "email": "John@example.com", - "ips": [ -​ "1.1.1.1", -​ "2.2.2.2" - ], - "password": "johns_password", - "username": "John@example.com" -} -response = sg.client.subusers.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 - -Classroom > How do I add more subusers to my account? - -GET /subusers - - -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 - -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. - -This endpoint allows you to request the reputations for your subusers. - -GET /subusers/reputations - - -params = {'usernames': 'test_string'} -response = sg.client.subusers.reputations.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve email statistics for your subusers. - -This endpoint allows you to retrieve the email statistics for the given subusers. - -You may retrieve statistics for up to 10 different subusers by including an additional subusers parameter for each additional subuser. - -While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - -For more information, see our User Guide. - -GET /subusers/stats - - -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) -print response.status_code -print response.body -print response.headers -Retrieve monthly stats for all subusers - -This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range. - -While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - -When using the sort_by_metric to sort your stats by a specific metric, you can not sort by the following metrics: -bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops. - -For more information, see our User Guide. - -GET /subusers/stats/monthly - - -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) -print response.status_code -print response.body -print response.headers -Retrieve the totals for each email statistic metric for all subusers. - -This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range. - -While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - -For more information, see our User Guide. - -GET /subusers/stats/sums - - -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) -print response.status_code -print response.body -print response.headers -Enable/disable a subuser - -This endpoint allows you to enable or disable a subuser. - -For more information about Subusers: - -User Guide > Subusers - -Classroom > How do I add more subusers to my account? - -PATCH /subusers/{subuser_name} - - -data = { - "disabled": False -} -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Delete a subuser - -This endpoint allows you to delete a subuser. This is a permanent action, once you delete a subuser it cannot be retrieved. - -For more information about Subusers: - -User Guide > Subusers - -Classroom > How do I add more subusers to my account? - -DELETE /subusers/{subuser_name} - - -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).delete() -print response.status_code -print response.body -print response.headers -Update IPs assigned to a subuser - -Each subuser should be assigned to an IP address, from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have their own, or multiple, IP addresses as well. - -More information: - -How to request more IPs - -IPs can be whitelabeled - -PUT /subusers/{subuser_name}/ips - - -data = [ - "127.0.0.1" -] -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).ips.put(request_body=data) -print response.status_code -print response.body -print response.headers -Update Monitor Settings for a subuser - -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - -PUT /subusers/{subuser_name}/monitor - - -data = { - "email": "example@example.com", - "frequency": 500 -} -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.put(request_body=data) -print response.status_code -print response.body -print response.headers -Create monitor settings - -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - -POST /subusers/{subuser_name}/monitor - - -data = { - "email": "example@example.com", - "frequency": 50000 -} -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve monitor settings for a subuser - -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - -GET /subusers/{subuser_name}/monitor - - -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.get() -print response.status_code -print response.body -print response.headers -Delete monitor settings - -Subuser monitor settings allow you to receive a sample of an outgoing message by a specific customer at a specific frequency of emails. - -DELETE /subusers/{subuser_name}/monitor - - -subuser_name = "test_url_param" -response = sg.client.subusers._(subuser_name).monitor.delete() -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. - -While you can always view the statistics for all email activity on your account, subuser statistics enable you to view specific segments of your stats for your subusers. Emails sent, bounces, and spam reports are always tracked for subusers. Unsubscribes, clicks, and opens are tracked if you have enabled the required settings. - -When using the sort_by_metric to sort your stats by a specific metric, you can not sort by the following metrics: -bounce_drops, deferred, invalid_emails, processed, spam_report_drops, spam_reports, or unsubscribe_drops. - -For more information, see our User Guide. - -GET /subusers/{subuser_name}/stats/monthly - - -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) -print response.status_code -print response.body -print response.headers - - -SUPPRESSION - -Retrieve all blocks - -This endpoint allows you to retrieve a list of all email addresses that are currently on your blocks list. - -Blocks 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. - -GET /suppression/blocks - - -params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} -response = sg.client.suppression.blocks.get(query_params=params) -print response.status_code -print response.body -print response.headers -Delete blocks - -This endpoint allows you to delete all email addresses on your blocks list. - -There are two options for deleting blocked emails: - -You can delete all blocked emails by setting delete_all to true in the request body. - -You can delete some blocked emails by specifying the email addresses in an array in the request body. - -Blocks 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. - -DELETE /suppression/blocks - - -data = { - "delete_all": False, - "emails": [ -​ "example1@example.com", -​ "example2@example.com" - ] -} -response = sg.client.suppression.blocks.delete(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a specific block - -This endpoint allows you to retrieve a specific email address from your blocks list. - -Blocks 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. - -GET /suppression/blocks/{email} - - -email = "test_url_param" -response = sg.client.suppression.blocks._(email).get() -print response.status_code -print response.body -print response.headers -Delete a specific block - -This endpoint allows you to delete a specific email address from your blocks list. - -Blocks 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. - -DELETE /suppression/blocks/{email} - - -email = "test_url_param" -response = sg.client.suppression.blocks._(email).delete() -print response.status_code -print response.body -print response.headers -Retrieve all bounces - -This endpoint allows you to retrieve all of your bounces. - -Bounces are messages that are returned to the server that sent it. - -For more information see: - -User Guide > Bounces for more information - -Glossary > Bounces - -GET /suppression/bounces - - -params = {'start_time': 1, 'end_time': 1} -response = sg.client.suppression.bounces.get(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. - -For more information see: - -User Guide > Bounces for more information - -Glossary > Bounces - -Classroom > List Scrubbing Guide - -Note: the delete_all and emails parameters should be used independently of each other as they have different purposes. - -DELETE /suppression/bounces - - -data = { - "delete_all": True, - "emails": [ -​ "example@example.com", -​ "example2@example.com" - ] -} -response = sg.client.suppression.bounces.delete(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a Bounce - -This endpoint allows you to retrieve a specific bounce for a given email address. - -Bounces are messages that are returned to the server that sent it. - -For more information see: - -User Guide > Bounces for more information - -Glossary > Bounces - -Classroom > List Scrubbing Guide - -GET /suppression/bounces/{email} - - -email = "test_url_param" -response = sg.client.suppression.bounces._(email).get() -print response.status_code -print response.body -print response.headers -Delete a bounce - -This endpoint allows you to remove an email address from your bounce list. - -Bounces are messages that are returned to the server that sent it. This endpoint allows you to delete a single email address from your bounce list. - -For more information see: - -User Guide > Bounces for more information - -Glossary > Bounces - -Classroom > List Scrubbing Guide - -DELETE /suppression/bounces/{email} - - -params = {'email_address': 'example@example.com'} -email = "test_url_param" -response = sg.client.suppression.bounces._(email).delete(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve all invalid emails - -This endpoint allows you to retrieve a list of all invalid email addresses. - -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. - -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - -For more information, please see our User Guide. - -GET /suppression/invalid_emails - - -params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} -response = sg.client.suppression.invalid_emails.get(query_params=params) -print response.status_code -print response.body -print response.headers -Delete invalid emails - -This endpoint allows you to remove email addresses from your invalid email address list. - -There are two options for deleting invalid email addresses: - -1) You can delete all invalid email addresses by setting delete_all to true in the request body. -2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. - -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. - -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - -For more information, please see our User Guide. - -DELETE /suppression/invalid_emails - - -data = { - "delete_all": False, - "emails": [ -​ "example1@example.com", -​ "example2@example.com" - ] -} -response = sg.client.suppression.invalid_emails.delete(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a specific invalid email - -This endpoint allows you to retrieve a specific invalid email addresses. - -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. - -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - -For more information, please see our User Guide. - -GET /suppression/invalid_emails/{email} - - -email = "test_url_param" -response = sg.client.suppression.invalid_emails._(email).get() -print response.status_code -print response.body -print response.headers -Delete a specific invalid email - -This endpoint allows you to remove a specific email address from the invalid email address list. - -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. - -Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. - -For more information, please see our User Guide. - -DELETE /suppression/invalid_emails/{email} - - -email = "test_url_param" -response = sg.client.suppression.invalid_emails._(email).delete() -print response.status_code -print response.body -print response.headers -Retrieve a specific spam report - -This endpoint allows you to retrieve a specific spam report. - -Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. - -For more information, please see our User Guide. - -GET /suppression/spam_report/{email} - - -email = "test_url_param" -response = sg.client.suppression.spam_report._(email).get() -print response.status_code -print response.body -print response.headers -Delete a specific spam report - -This endpoint allows you to delete a specific spam report. - -Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. - -For more information, please see our User Guide. - -DELETE /suppression/spam_report/{email} - - -email = "test_url_param" -response = sg.client.suppression.spam_report._(email).delete() -print response.status_code -print response.body -print response.headers -Retrieve all spam reports - -This endpoint allows you to retrieve all spam reports. - -Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. - -For more information, please see our User Guide. - -GET /suppression/spam_reports - - -params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} -response = sg.client.suppression.spam_reports.get(query_params=params) -print response.status_code -print response.body -print response.headers -Delete spam reports - -This endpoint allows you to delete your spam reports. - -There are two options for deleting spam reports: - -1) You can delete all spam reports by setting "delete_all" to true in the request body. -2) You can delete some spam reports by specifying the email addresses in an array in the request body. - -Spam reports happen when a recipient indicates that they think your email is spam and then their email provider reports this to SendGrid. - -For more information, please see our User Guide. - -DELETE /suppression/spam_reports - - -data = { - "delete_all": False, - "emails": [ -​ "example1@example.com", -​ "example2@example.com" - ] -} -response = sg.client.suppression.spam_reports.delete(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all global suppressions - -This endpoint allows you to retrieve a list of all email address that are globally suppressed. - -A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our User Guide. - -GET /suppression/unsubscribes - - -params = {'start_time': 1, 'limit': 1, 'end_time': 1, 'offset': 1} -response = sg.client.suppression.unsubscribes.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -TEMPLATES - -Create a transactional template. - -This endpoint allows you to create a transactional template. - -Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - -Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. - -POST /templates - - -data = { - "name": "example_name" -} -response = sg.client.templates.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all transactional templates. - -This endpoint allows you to retrieve all transactional templates. - -Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - -Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. - -GET /templates - - -response = sg.client.templates.get() -print response.status_code -print response.body -print response.headers -Edit a transactional template. - -This endpoint allows you to edit a transactional template. - -Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - -Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. - -PATCH /templates/{template_id} - - -data = { - "name": "new_example_name" -} -template_id = "test_url_param" -response = sg.client.templates._(template_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a single transactional template. - -This endpoint allows you to retrieve a single transactional template. - -Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - -Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. - -GET /templates/{template_id} - - -template_id = "test_url_param" -response = sg.client.templates._(template_id).get() -print response.status_code -print response.body -print response.headers -Delete a template. - -This endpoint allows you to delete a transactional template. - -Each user can create up to 300 different transactional templates. Transactional templates are specific to accounts and subusers. Templates created on a parent account will not be accessible from the subuser accounts. - -Transactional templates are templates created specifically for transactional email and are not to be confused with Marketing Campaigns templates. For more information about transactional templates, please see our User Guide. - -DELETE /templates/{template_id} - - -template_id = "test_url_param" -response = sg.client.templates._(template_id).delete() -print response.status_code -print response.body -print response.headers -Create a new transactional template version. - -This endpoint allows you to create a new version of a template. - -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - -For more information about transactional templates, please see our User Guide. - -POST /templates/{template_id}/versions - - -data = { - "active": 1, - "html_content": "<%body%>", - "name": "example_version_name", - "plain_content": "<%body%>", - "subject": "<%subject%>", - "template_id": "ddb96bbc-9b92-425e-8979-99464621b543" -} -template_id = "test_url_param" -response = sg.client.templates._(template_id).versions.post(request_body=data) -print response.status_code -print response.body -print response.headers -Edit a transactional template version. - -This endpoint allows you to edit a version of one of your transactional templates. - -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - -For more information about transactional templates, please see our User Guide. - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -template_id string The ID of the original template -version_id string The ID of the template version -PATCH /templates/{template_id}/versions/{version_id} - - -data = { - "active": 1, - "html_content": "<%body%>", - "name": "updated_example_name", - "plain_content": "<%body%>", - "subject": "<%subject%>" -} -template_id = "test_url_param" -version_id = "test_url_param" -response = sg.client.templates._(template_id).versions._(version_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a specific transactional template version. - -This endpoint allows you to retrieve a specific version of a template. - -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - -For more information about transactional templates, please see our User Guide. - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -template_id string The ID of the original template -version_id string The ID of the template version -GET /templates/{template_id}/versions/{version_id} - - -template_id = "test_url_param" -version_id = "test_url_param" -response = sg.client.templates._(template_id).versions._(version_id).get() -print response.status_code -print response.body -print response.headers -Delete a transactional template version. - -This endpoint allows you to delete one of your transactional template versions. - -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - -For more information about transactional templates, please see our User Guide. - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -template_id string The ID of the original template -version_id string The ID of the template version -DELETE /templates/{template_id}/versions/{version_id} - - -template_id = "test_url_param" -version_id = "test_url_param" -response = sg.client.templates._(template_id).versions._(version_id).delete() -print response.status_code -print response.body -print response.headers -Activate a transactional template version. - -This endpoint allows you to activate a version of one of your templates. - -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. - -For more information about transactional templates, please see our User Guide. - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -template_id string The ID of the original template -version_id string The ID of the template version -POST /templates/{template_id}/versions/{version_id}/activate - - -template_id = "test_url_param" -version_id = "test_url_param" -response = sg.client.templates._(template_id).versions._(version_id).activate.post() -print response.status_code -print response.body -print response.headers - - -TRACKING SETTINGS - -Retrieve Tracking Settings - -This endpoint allows you to retrieve a list of all tracking settings that you can enable on your account. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -GET /tracking_settings - - -params = {'limit': 1, 'offset': 1} -response = sg.client.tracking_settings.get(query_params=params) -print response.status_code -print response.body -print response.headers -Update Click Tracking Settings - -This endpoint allows you to change your current click tracking setting. You can enable, or disable, click tracking using this endpoint. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -PATCH /tracking_settings/click - - -data = { - "enabled": True -} -response = sg.client.tracking_settings.click.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve Click Track Settings - -This endpoint allows you to retrieve your current click tracking setting. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -GET /tracking_settings/click - - -response = sg.client.tracking_settings.click.get() -print response.status_code -print response.body -print response.headers -Update Google Analytics Settings - -This endpoint allows you to update your current setting for Google Analytics. - -For more information about using Google Analytics, please refer to Googles URL Builder and their article on "Best Practices for Campaign Building". - -We default the settings to Googles recommendations. For more information, see Google Analytics Demystified. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -PATCH /tracking_settings/google_analytics - - -data = { - "enabled": True, - "utm_campaign": "website", - "utm_content": "", - "utm_medium": "email", - "utm_source": "sendgrid.com", - "utm_term": "" -} -response = sg.client.tracking_settings.google_analytics.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve Google Analytics Settings - -This endpoint allows you to retrieve your current setting for Google Analytics. - -For more information about using Google Analytics, please refer to Googles URL Builder and their article on "Best Practices for Campaign Building". - -We default the settings to Googles recommendations. For more information, see Google Analytics Demystified. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -GET /tracking_settings/google_analytics - - -response = sg.client.tracking_settings.google_analytics.get() -print response.status_code -print response.body -print response.headers -Update Open Tracking Settings - -This endpoint allows you to update your current settings for open tracking. - -Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -PATCH /tracking_settings/open - - -data = { - "enabled": True -} -response = sg.client.tracking_settings.open.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Get Open Tracking Settings - -This endpoint allows you to retrieve your current settings for open tracking. - -Open Tracking adds an invisible image at the end of the email which can track email opens. If the email recipient has images enabled on their email client, a request to SendGrids server for the invisible image is executed and an open event is logged. These events are logged in the Statistics portal, Email Activity interface, and are reported by the Event Webhook. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -GET /tracking_settings/open - - -response = sg.client.tracking_settings.open.get() -print response.status_code -print response.body -print response.headers -Update Subscription Tracking Settings - -This endpoint allows you to update your current settings for subscription tracking. - -Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -PATCH /tracking_settings/subscription - - -data = { - "enabled": True, - "html_content": "html content", - "landing": "landing page html", - "plain_content": "text content", - "replace": "replacement tag", - "url": "url" -} -response = sg.client.tracking_settings.subscription.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve Subscription Tracking Settings - -This endpoint allows you to retrieve your current settings for subscription tracking. - -Subscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails. - -You can track a variety of the actions your recipients may take when interacting with your emails including opening your emails, clicking on links in your emails, and subscribing to (or unsubscribing from) your emails. - -For more information about tracking, please see our User Guide. - -GET /tracking_settings/subscription - - -response = sg.client.tracking_settings.subscription.get() -print response.status_code -print response.body -print response.headers - - -USER - -Get a user's account information. - -This endpoint allows you to retrieve your user account details. - -Your user's account information includes the user's account type and reputation. - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -GET /user/account - - -response = sg.client.user.account.get() -print response.status_code -print response.body -print response.headers -Retrieve your credit balance - -This endpoint allows you to retrieve the current credit balance for your account. - -Your monthly credit allotment limits the number of emails you may send before incurring overage charges. For more information about credits and billing, please visit our Classroom. - -GET /user/credits - - -response = sg.client.user.credits.get() -print response.status_code -print response.body -print response.headers -Update your account email address - -This endpoint allows you to update the email address currently on file for your account. - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -PUT /user/email - - -data = { - "email": "example@example.com" -} -response = sg.client.user.email.put(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve your account email address - -This endpoint allows you to retrieve the email address currently on file for your account. - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -GET /user/email - - -response = sg.client.user.email.get() -print response.status_code -print response.body -print response.headers -Update your password - -This endpoint allows you to update your password. - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -PUT /user/password - - -data = { - "new_password": "new_password", - "old_password": "old_password" -} -response = sg.client.user.password.put(request_body=data) -print response.status_code -print response.body -print response.headers -Update a user's profile - -This endpoint allows you to update your current profile details. - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -It should be noted that any one or more of the parameters can be updated via the PATCH /user/profile endpoint. The only requirement is that you include at least one when you PATCH. - -PATCH /user/profile - - -data = { - "city": "Orange", - "first_name": "Example", - "last_name": "User" -} -response = sg.client.user.profile.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Get a user's profile - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -GET /user/profile - - -response = sg.client.user.profile.get() -print response.status_code -print response.body -print response.headers -Cancel or pause a scheduled send - -This endpoint allows you to cancel or pause an email that has been scheduled to be sent. - -If the maximum number of cancellations/pauses are added, HTTP 400 will -be returned. - -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - -POST /user/scheduled_sends - - -data = { - "batch_id": "YOUR_BATCH_ID", - "status": "pause" -} -response = sg.client.user.scheduled_sends.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all scheduled sends - -This endpoint allows you to retrieve all cancel/paused scheduled send information. - -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - -GET /user/scheduled_sends - - -response = sg.client.user.scheduled_sends.get() -print response.status_code -print response.body -print response.headers -Update user scheduled send information - -This endpoint allows you to update the status of a scheduled send for the given batch_id. - -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - -PATCH /user/scheduled_sends/{batch_id} - - -data = { - "status": "pause" -} -batch_id = "test_url_param" -response = sg.client.user.scheduled_sends._(batch_id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve scheduled send - -This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific batch_id. - -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - -GET /user/scheduled_sends/{batch_id} - - -batch_id = "test_url_param" -response = sg.client.user.scheduled_sends._(batch_id).get() -print response.status_code -print response.body -print response.headers -Delete a cancellation or pause of a scheduled send - -This endpoint allows you to delete the cancellation/pause of a scheduled send. - -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. - -DELETE /user/scheduled_sends/{batch_id} - - -batch_id = "test_url_param" -response = sg.client.user.scheduled_sends._(batch_id).delete() -print response.status_code -print response.body -print response.headers -Update Enforced TLS settings - -This endpoint allows you to update your current Enforced TLS settings. - -The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the SMTP Ports User Guide for more information on opportunistic TLS. - -Note: If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with TLS required but not supported as the description. - -PATCH /user/settings/enforced_tls - - -data = { - "require_tls": True, - "require_valid_cert": False -} -response = sg.client.user.settings.enforced_tls.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve current Enforced TLS settings. - -This endpoint allows you to retrieve your current Enforced TLS settings. - -The Enforced TLS settings specify whether or not the recipient is required to support TLS or have a valid certificate. See the SMTP Ports User Guide for more information on opportunistic TLS. - -Note: If either setting is enabled and the recipient does not support TLS or have a valid certificate, we drop the message and send a block event with TLS required but not supported as the description. - -GET /user/settings/enforced_tls - - -response = sg.client.user.settings.enforced_tls.get() -print response.status_code -print response.body -print response.headers -Update your username - -This endpoint allows you to update the username for your account. - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -PUT /user/username - - -data = { - "username": "test_username" -} -response = sg.client.user.username.put(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve your username - -This endpoint allows you to retrieve your current account username. - -Keeping your user profile up to date is important. This will help SendGrid to verify who you are as well as contact you should we need to. - -For more information about your user profile: - -SendGrid Account Settings - -GET /user/username - - -response = sg.client.user.username.get() -print response.status_code -print response.body -print response.headers -Update Event Notification Settings - -This endpoint allows you to update your current event webhook settings. - -If an event type is marked as true, then the event webhook will include information about that event. - -SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - -Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - -PATCH /user/webhooks/event/settings - - -data = { - "bounce": True, - "click": True, - "deferred": True, - "delivered": True, - "dropped": True, - "enabled": True, - "group_resubscribe": True, - "group_unsubscribe": True, - "open": True, - "processed": True, - "spam_report": True, - "unsubscribe": True, - "url": "url" -} -response = sg.client.user.webhooks.event.settings.patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve Event Webhook settings - -This endpoint allows you to retrieve your current event webhook settings. - -If an event type is marked as true, then the event webhook will include information about that event. - -SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - -Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - -GET /user/webhooks/event/settings - - -response = sg.client.user.webhooks.event.settings.get() -print response.status_code -print response.body -print response.headers -Test Event Notification Settings - -This endpoint allows you to test your event webhook by sending a fake event notification post to the provided URL. - -SendGrids Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. - -Common uses of this data are to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. - -POST /user/webhooks/event/test - - -data = { - "url": "url" -} -response = sg.client.user.webhooks.event.test.post(request_body=data) -print response.status_code -print response.body -print response.headers -Create a parse setting - -This endpoint allows you to create a new inbound parse setting. - -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. - -POST /user/webhooks/parse/settings - - -data = { - "hostname": "myhostname.com", - "send_raw": False, - "spam_check": True, - "url": "http://email.myhosthame.com" -} -response = sg.client.user.webhooks.parse.settings.post(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve all parse settings - -This endpoint allows you to retrieve all of your current inbound parse settings. - -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. - -GET /user/webhooks/parse/settings - - -response = sg.client.user.webhooks.parse.settings.get() -print response.status_code -print response.body -print response.headers -Update a parse setting - -This endpoint allows you to update a specific inbound parse setting. - -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. - -PATCH /user/webhooks/parse/settings/{hostname} - - -data = { - "send_raw": True, - "spam_check": False, - "url": "http://newdomain.com/parse" -} -hostname = "test_url_param" -response = sg.client.user.webhooks.parse.settings._(hostname).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a specific parse setting - -This endpoint allows you to retrieve a specific inbound parse setting. - -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. - -GET /user/webhooks/parse/settings/{hostname} - - -hostname = "test_url_param" -response = sg.client.user.webhooks.parse.settings._(hostname).get() -print response.status_code -print response.body -print response.headers -Delete a parse setting - -This endpoint allows you to delete a specific inbound parse setting. - -The inbound parse webhook allows you to have incoming emails parsed, extracting some or all of the content, and then have that content POSTed by SendGrid to a URL of your choosing. For more information, please see our User Guide. - -DELETE /user/webhooks/parse/settings/{hostname} - - -hostname = "test_url_param" -response = sg.client.user.webhooks.parse.settings._(hostname).delete() -print response.status_code -print response.body -print response.headers -Retrieves Inbound Parse Webhook statistics. - -This endpoint allows you to retrieve the statistics for your Parse Webhook usage. - -SendGrid's Inbound Parse Webhook allows you to parse the contents and attachments of incoming emails. The Parse API can then POST the parsed emails to a URL that you specify. The Inbound Parse Webhook cannot parse messages greater than 20MB in size, including all attachments. - -There are a number of pre-made integrations for the SendGrid Parse Webhook which make processing events easy. You can find these integrations in the Library Index. - -GET /user/webhooks/parse/stats - - -params = {'aggregated_by': 'day', 'limit': 'test_string', 'start_date': '2016-01-01', 'end_date': '2016-04-01', 'offset': 'test_string'} -response = sg.client.user.webhooks.parse.stats.get(query_params=params) -print response.status_code -print response.body -print response.headers - - -WHITELABEL - -Create a domain whitelabel. - -This endpoint allows you to create a whitelabel for one of your domains. - -If you are creating a domain whitelabel that you would like a subuser to use, you have two options: - -Use the "username" parameter. This allows you to create a whitelabel on behalf of your subuser. This means the subuser is able to see and modify the created whitelabel. - -Use the Association workflow (see Associate Domain section). This allows you to assign a whitelabel created by the parent to a subuser. This means the subuser will default to the assigned whitelabel, but will not be able to see or modify that whitelabel. However, if the subuser creates their own whitelabel it will overwrite the assigned whitelabel. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -POST /whitelabel/domains - - -data = { - "automatic_security": False, - "custom_spf": True, - "default": True, - "domain": "example.com", - "ips": [ -​ "192.168.1.1", -​ "192.168.1.2" - ], - "subdomain": "news", - "username": "john@example.com" -} -response = sg.client.whitelabel.domains.post(request_body=data) -print response.status_code -print response.body -print response.headers -List all domain whitelabels. - -This endpoint allows you to retrieve a list of all domain whitelabels you have created. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -GET /whitelabel/domains - - -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 -Get the default domain whitelabel. - -This endpoint allows you to retrieve the default whitelabel for a domain. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -domain string The domain to find a default domain whitelabel for. -GET /whitelabel/domains/default - - -response = sg.client.whitelabel.domains.default.get() -print response.status_code -print response.body -print response.headers -List the domain whitelabel associated with the given user. - -This endpoint allows you to retrieve all of the whitelabels that have been assigned to a specific subuser. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. - -For more information on whitelabeling, please see our User Guide - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -username string Username of the subuser to find associated whitelabels for. -GET /whitelabel/domains/subuser - - -response = sg.client.whitelabel.domains.subuser.get() -print response.status_code -print response.body -print response.headers -Disassociate a domain whitelabel from a given user. - -This endpoint allows you to disassociate a specific whitelabel from a subuser. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. - -For more information on whitelabeling, please see our User Guide - -URI Parameters - -URI PARAMETER TYPE REQUIRED? DESCRIPTION -username string required Username for the subuser to find associated whitelabels for. -DELETE /whitelabel/domains/subuser - - -response = sg.client.whitelabel.domains.subuser.delete() -print response.status_code -print response.body -print response.headers -Update a domain whitelabel. - -This endpoint allows you to update the settings for a domain whitelabel. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -PATCH /whitelabel/domains/{domain_id} - - -data = { - "custom_spf": True, - "default": False -} -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 -Retrieve a domain whitelabel. - -This endpoint allows you to retrieve a specific domain whitelabel. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -GET /whitelabel/domains/{domain_id} - - -domain_id = "test_url_param" -response = sg.client.whitelabel.domains._(domain_id).get() -print response.status_code -print response.body -print response.headers -Delete a domain whitelabel. - -This endpoint allows you to delete a domain whitelabel. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -DELETE /whitelabel/domains/{domain_id} - - -domain_id = "test_url_param" -response = sg.client.whitelabel.domains._(domain_id).delete() -print response.status_code -print response.body -print response.headers -Associate a domain whitelabel with a given user. - -This endpoint allows you to associate a specific domain whitelabel with a subuser. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -Domain whitelabels can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's whitelabels. To associate a whitelabel with a subuser, the parent account must first create the whitelabel and validate it. The parent may then associate the whitelabel via the subuser management tools. - -For more information on whitelabeling, please see our User Guide - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -domain_id integer ID of the domain whitelabel to associate with the subuser. -POST /whitelabel/domains/{domain_id}/subuser - - -data = { - "username": "jane@example.com" -} -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 -Add an IP to a domain whitelabel. - -This endpoint allows you to add an IP address to a domain whitelabel. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -id integer ID of the domain to which you are adding an IP -POST /whitelabel/domains/{id}/ips - - -data = { - "ip": "192.168.0.1" -} -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 -Remove an IP from a domain whitelabel. - -This endpoint allows you to remove a domain's IP address from that domain's whitelabel. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -id integer ID of the domain whitelabel to delete the IP from. -ip string IP to remove from the domain whitelabel. -DELETE /whitelabel/domains/{id}/ips/{ip} - - -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 -Validate a domain whitelabel. - -This endpoint allows you to validate a domain whitelabel. If it fails, it will return an error message describing why the whitelabel could not be validated. - -A domain whitelabel allows you to remove the via or sent on behalf of message that your recipients see when they read your emails. Whitelabeling a domain allows you to replace sendgrid.net with your personal sending domain. You will be required to create a subdomain so that SendGrid can generate the DNS records which you must give to your host provider. If you choose to use Automated Security, SendGrid will provide you with 3 CNAME records. If you turn Automated Security off, you will be given 2 TXT records and 1 MX record. - -For more information on whitelabeling, please see our User Guide - -URI Parameters - -URI PARAMETER TYPE DESCRIPTION -id integer ID of the domain whitelabel to validate. -POST /whitelabel/domains/{id}/validate - - -id = "test_url_param" -response = sg.client.whitelabel.domains._(id).validate.post() -print response.status_code -print response.body -print response.headers -Create an IP whitelabel - -This endpoint allows you to create an IP whitelabel. - -When creating an IP whitelable, you should use the same subdomain that you used when you created a domain whitelabel. - -A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - -For more information, please see our User Guide. - -POST /whitelabel/ips - - -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 -Retrieve all IP whitelabels - -This endpoint allows you to retrieve all of the IP whitelabels that have been created by this account. - -You may include a search key by using the "ip" parameter. This enables you to perform a prefix search for a given IP segment (e.g. "192."). - -A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - -For more information, please see our User Guide. - -GET /whitelabel/ips - - -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 -Retrieve an IP whitelabel - -This endpoint allows you to retrieve an IP whitelabel. - -A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - -For more information, please see our User Guide. - -GET /whitelabel/ips/{id} - - -id = "test_url_param" -response = sg.client.whitelabel.ips._(id).get() -print response.status_code -print response.body -print response.headers -Delete an IP whitelabel - -This endpoint allows you to delete an IP whitelabel. - -A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - -For more information, please see our User Guide. - -DELETE /whitelabel/ips/{id} - - -id = "test_url_param" -response = sg.client.whitelabel.ips._(id).delete() -print response.status_code -print response.body -print response.headers -Validate an IP whitelabel - -This endpoint allows you to validate an IP whitelabel. - -A IP whitelabel consists of a subdomain and domain that will be used to generate a reverse DNS record for a given IP. Once SendGrid has verified that the appropriate A record for the IP has been created, the appropriate reverse DNS record for the IP is generated. - -For more information, please see our User Guide. - -POST /whitelabel/ips/{id}/validate - - -id = "test_url_param" -response = sg.client.whitelabel.ips._(id).validate.post() -print response.status_code -print response.body -print response.headers -Create a Link Whitelabel - -This endpoint allows you to create a new link whitelabel. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -POST /whitelabel/links - - -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 -Retrieve all link whitelabels - -This endpoint allows you to retrieve all link whitelabels. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -GET /whitelabel/links - - -params = {'limit': 1} -response = sg.client.whitelabel.links.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve a Default Link Whitelabel - -This endpoint allows you to retrieve the default link whitelabel. - -Default link whitelabel is the actual link whitelabel to be used when sending messages. If there are multiple link whitelabels, the default is determined by the following order: - - -Validated link whitelabels marked as "default" -Legacy link whitelabels (migrated from the whitelabel wizard) -Default SendGrid link whitelabel (i.e. 100.ct.sendgrid.net) - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -GET /whitelabel/links/default - - -params = {'domain': 'test_string'} -response = sg.client.whitelabel.links.default.get(query_params=params) -print response.status_code -print response.body -print response.headers -Retrieve Associated Link Whitelabel - -This endpoint allows you to retrieve the associated link whitelabel for a subuser. - -Link whitelables can be associated with subusers from the parent account. This functionality allows -subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account -must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -GET /whitelabel/links/subuser - - -params = {'username': 'test_string'} -response = sg.client.whitelabel.links.subuser.get(query_params=params) -print response.status_code -print response.body -print response.headers -Disassociate a Link Whitelabel - -This endpoint allows you to disassociate a link whitelabel from a subuser. - -Link whitelables can be associated with subusers from the parent account. This functionality allows -subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account -must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -DELETE /whitelabel/links/subuser - - -params = {'username': 'test_string'} -response = sg.client.whitelabel.links.subuser.delete(query_params=params) -print response.status_code -print response.body -print response.headers -Update a Link Whitelabel - -This endpoint allows you to update a specific link whitelabel. You can use this endpoint to change a link whitelabel's default status. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -PATCH /whitelabel/links/{id} - - -data = { - "default": True -} -id = "test_url_param" -response = sg.client.whitelabel.links._(id).patch(request_body=data) -print response.status_code -print response.body -print response.headers -Retrieve a Link Whitelabel - -This endpoint allows you to retrieve a specific link whitelabel. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -GET /whitelabel/links/{id} - - -id = "test_url_param" -response = sg.client.whitelabel.links._(id).get() -print response.status_code -print response.body -print response.headers -Delete a Link Whitelabel - -This endpoint allows you to delete a link whitelabel. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -DELETE /whitelabel/links/{id} - - -id = "test_url_param" -response = sg.client.whitelabel.links._(id).delete() -print response.status_code -print response.body -print response.headers -Validate a Link Whitelabel - -This endpoint allows you to validate a link whitelabel. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -POST /whitelabel/links/{id}/validate - - -id = "test_url_param" -response = sg.client.whitelabel.links._(id).validate.post() -print response.status_code -print response.body -print response.headers -Associate a Link Whitelabel - -This endpoint allows you to associate a link whitelabel with a subuser account. - -Link whitelables can be associated with subusers from the parent account. This functionality allows -subusers to send mail using their parent's link whitelabels. To associate a link whitelabel, the parent account -must first create a whitelabel and validate it. The parent may then associate that whitelabel with a subuser via the API or the Subuser Management page in the user interface. - -Email link whitelabels allow all of the click-tracked links you send in your emails to include the URL of your domain instead of sendgrid.net. - -For more information, please see our User Guide. - -POST /whitelabel/links/{link_id}/subuser - - -data = { - "username": "jane@example.com" -} -link_id = "test_url_param" -response = sg.client.whitelabel.links._(link_id).subuser.post(request_body=data) -print response.status_code -print response.body -print response.headersPOST /access_settings/whitelist +### POST /access_settings/whitelist ```python @@ -4912,7 +291,7 @@ print response.headers **This endpoint allows you to create a new random API Key for the user.** -A JSON request body containing a "name" property is required. If number of maximum keys is reached, HTTP 403 will be returned. +A JSON request body containing a "name" property is required. If the number of maximum keys is reached, HTTP 403 will be returned. There is a limit of 100 API Keys on your account. @@ -4959,7 +338,7 @@ print response.headers **This endpoint allows you to update the name and scopes of a given API key.** A JSON request body with a "name" property is required. -Most provide the list of all the scopes an api key should have. +Most provide the list of all the scopes an API key should have. The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). @@ -5028,7 +407,7 @@ print response.headers **This endpoint allows you to revoke an existing API Key.** -Authentications using this API Key will fail after this request is made, with some small propagation delay.If the API Key ID does not exist an HTTP 404 will be returned. +Authentications using this API Key will fail after this request is made, with some small propagation delay. If the API Key ID does not exist an HTTP 404 will be returned. The API Keys feature allows customers to be able to generate an API Key credential which can be used for authentication with the SendGrid v3 Web API or the [Mail API Endpoint](https://sendgrid.com/docs/API_Reference/Web_API/mail.html). @@ -5055,7 +434,7 @@ print response.headers **This endpoint allows you to create a new suppression group.** -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example Daily Newsletters, Invoices, System Alerts. The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. @@ -5099,7 +478,7 @@ print response.headers **This endpoint allows you to update or change a suppression group.** -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example Daily Newsletters, Invoices, System Alerts. The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. @@ -5124,7 +503,7 @@ print response.headers **This endpoint allows you to retrieve a single suppression group.** -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example Daily Newsletters, Invoices, System Alerts. The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. @@ -5146,7 +525,7 @@ print response.headers You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the "one-click unsubscribe" option on an email associated with a deleted group, that recipient will be added to the global suppression list. -Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example: Daily Newsletters, Invoices, System Alerts. +Suppression groups, or unsubscribe groups, are specific types or categories of emails that you would like your recipients to be able to unsubscribe from. For example Daily Newsletters, Invoices, System Alerts. The **name** and **description** of the unsubscribe group will be visible by recipients when they are managing their subscriptions. @@ -5333,7 +712,7 @@ print response.headers # BROWSERS -## Retrieve email statistics by browser. +## Retrieve email statistics by the browser. **This endpoint allows you to retrieve your email statistics segmented by browser type.** @@ -5360,7 +739,7 @@ print response.headers Our Marketing Campaigns API lets you create, manage, send, and schedule campaigns. -Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign. +Note: In order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both HTML and plain text), and at least one list or segment ID. This information is not required when you create a campaign. For more information: @@ -6039,7 +1418,7 @@ print response.headers ``` ## Delete Recipient -**This endpoint allows you to deletes one or more recipients.** +**This endpoint allows you to delete one or more recipients.** The body of an API call to this endpoint must include an array of recipient IDs of the recipients you want to delete. @@ -6097,7 +1476,7 @@ print response.headers field_name: * is a variable that is substituted for your actual custom field name from your recipient. -* Text fields must be url-encoded. Date fields are searchable only by unix timestamp (e.g. 2/2/2015 becomes 1422835200) +* Text fields must be url-encoded. Date fields are searchable only by Unix timestamp (e.g. 2/2/2015 becomes 1422835200) * If field_name is a 'reserved' date field, such as created_at or updated_at, the system will internally convert your epoch time to a date range encompassing the entire day. For example, an epoch time of 1422835600 converts to Mon, 02 Feb 2015 00:06:40 GMT, but internally the system will search from Mon, 02 Feb 2015 00:00:00 GMT through @@ -6151,7 +1530,7 @@ print response.headers **This endpoint allows you to retrieve the lists that a given recipient belongs to.** -Each recipient can be on many lists. This endpoint gives you all of the lists that any one recipient has been added to. +Each recipient can be on many lists. This endpoint gives you all of the lists that anyone recipient has been added to. The Contacts API helps you manage your [Marketing Campaigns](https://sendgrid.com/docs/User_Guide/Marketing_Campaigns/index.html) recipients. @@ -6308,7 +1687,7 @@ print response.headers ``` ## Delete a segment -**This endpoint allows you to delete a segment from your recipients database.** +**This endpoint allows you to delete a segment from your recipient's database.** You also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment. @@ -6358,10 +1737,10 @@ print response.headers ## Available Device Types | **Device** | **Description** | **Example** | |---|---|---| -| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. | +| Desktop | Email software on a desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. | | Webmail | A web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. | -| Phone | A smart phone. | iPhone, Android, Blackberry, etc. -| Tablet | A tablet computer. | iPad, android based tablet, etc. | +| Phone | A smartphone. | iPhone, Android, Blackberry, etc. +| Tablet | A tablet computer. | iPad, Android-based tablet, etc. | | Other | An unrecognized device. | Advanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html). @@ -6404,7 +1783,7 @@ print response.headers **This endpoint allows you to retrieve a list of all assigned and unassigned IPs.** -Response includes warm up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. +The response includes warm-up status, pools, assigned subusers, and whitelabel info. The start_date field corresponds to when warmup started for that IP. A single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it. @@ -6677,7 +2056,7 @@ print response.headers **This endpoint allows you to generate a new batch ID. This batch ID can be associated with scheduled sends via the mail/send endpoint.** -If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. +If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mails/send requests together with the same ID. Then at any time up to 10 minutes before the scheduled date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. More Information: @@ -6696,7 +2075,7 @@ print response.headers **This endpoint allows you to validate a batch ID.** -If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mail/send requests together with the same ID. Then at anytime up to 10 minutes before the schedule date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. +If you set the SMTPAPI header `batch_id`, it allows you to then associate multiple scheduled mails/send requests together with the same ID. Then at anytime up to 10 minutes before the scheduled date, you can cancel all of the mail/send requests that have this batch ID by calling the Cancel Scheduled Send endpoint. More Information: @@ -6935,7 +2314,7 @@ 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, 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). @@ -6956,7 +2335,7 @@ 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, 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). @@ -7347,7 +2726,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 whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### POST /senders @@ -7379,7 +2758,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 whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### GET /senders @@ -7394,7 +2773,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 whitelabeled 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. @@ -7429,7 +2808,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 whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### GET /senders/{sender_id} @@ -7445,7 +2824,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 whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### DELETE /senders/{sender_id} @@ -7461,7 +2840,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 whitelabeled it will auto verify on creation. Otherwise, an email will be sent to the `from.email`. ### POST /senders/{sender_id}/resend_verification @@ -7543,7 +2922,7 @@ print response.headers ``` ## Retrieve Subuser Reputations -Subuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will effect your sender rating. +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 affect your sender rating. This endpoint allows you to request the reputations for your subusers. @@ -7952,7 +3331,7 @@ print response.headers **This endpoint allows you to retrieve a list of all invalid email addresses.** -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient's mail server. Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. @@ -7977,7 +3356,7 @@ There are two options for deleting invalid email addresses: 1) You can delete all invalid email addresses by setting `delete_all` to true in the request body. 2) You can delete some invalid email addresses by specifying certain addresses in an array in the request body. -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient's mail server. Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. @@ -8001,9 +3380,9 @@ print response.headers ``` ## Retrieve a specific invalid email -**This endpoint allows you to retrieve a specific invalid email addresses.** +**This endpoint allows you to retrieve a specific invalid email addresse.** -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient's mail server. Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. @@ -8023,7 +3402,7 @@ print response.headers **This endpoint allows you to remove a specific email address from the invalid email address list.** -An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipients mail server. +An invalid email occurs when you attempt to send email to an address that is formatted in a manner that does not meet internet email format standards or the email does not exist at the recipient's mail server. Examples include addresses without the @ sign or addresses that include certain special characters and/or spaces. This response can come from our own server or the recipient mail server. @@ -8124,7 +3503,7 @@ print response.headers ``` ## Retrieve all global suppressions -**This endpoint allows you to retrieve a list of all email address that are globally suppressed.** +**This endpoint allows you to retrieve a list of all email address that is globally suppressed.** A global suppression (or global unsubscribe) is an email address of a recipient who does not want to receive any of your messages. A globally suppressed recipient will be removed from any email you send. For more information, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Suppressions/global_unsubscribes.html). @@ -8242,7 +3621,7 @@ print response.headers **This endpoint allows you to create a new version of a template.** -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across all templates. For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). @@ -8269,7 +3648,7 @@ print response.headers **This endpoint allows you to edit a version of one of your transactional templates.** -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across all templates. For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). @@ -8301,7 +3680,7 @@ print response.headers **This endpoint allows you to retrieve a specific version of a template.** -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across all templates. For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). @@ -8326,7 +3705,7 @@ print response.headers **This endpoint allows you to delete one of your transactional template versions.** -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across all templates. For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). @@ -8351,7 +3730,7 @@ print response.headers **This endpoint allows you to activate a version of one of your templates.** -Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across across all templates. +Each transactional template can have multiple versions, each version with its own subject and content. Each user can have up to 300 versions across all templates. For more information about transactional templates, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Transactional_Templates/index.html). @@ -8721,7 +4100,7 @@ print response.headers If the maximum number of cancellations/pauses are added, HTTP 400 will be returned. -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. ### POST /user/scheduled_sends @@ -8740,7 +4119,7 @@ print response.headers **This endpoint allows you to retrieve all cancel/paused scheduled send information.** -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. ### GET /user/scheduled_sends @@ -8755,7 +4134,7 @@ print response.headers **This endpoint allows you to update the status of a scheduled send for the given `batch_id`.** -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. ### PATCH /user/scheduled_sends/{batch_id} @@ -8774,7 +4153,7 @@ print response.headers **This endpoint allows you to retrieve the cancel/paused scheduled send information for a specific `batch_id`.** -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. ### GET /user/scheduled_sends/{batch_id} @@ -8790,7 +4169,7 @@ print response.headers **This endpoint allows you to delete the cancellation/pause of a scheduled send.** -The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header.Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled. +The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends canceled less than 10 minutes before the scheduled time are not guaranteed to be canceled. ### DELETE /user/scheduled_sends/{batch_id}