The Official Twilio SendGrid Led, Community Driven Python API Library

Overview

SendGrid Logo

Travis Badge codecov Docker Badge Email Notifications Badge MIT licensed Twitter Follow GitHub contributors Open Source Helpers

The default branch name for this repository has been changed to main as of 07/27/2020.

This library allows you to quickly and easily use the SendGrid Web API v3 via Python.

Version 3.X.X+ of this library provides full support for all SendGrid Web API v3 endpoints, including the new v3 /mail/send.

This library represents the beginning of a new path for SendGrid. We want this library to be community driven and SendGrid led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create issues and pull requests or simply upvote or comment on existing issues or pull requests.

Please browse the rest of this README for further detail.

We appreciate your continued support, thank you!

Table of Contents

Installation

Prerequisites

  • Python version 2.7, 3.5, 3.6, 3.7, or 3.8
  • The SendGrid service, starting at the free level

Setup Environment Variables

Mac

Update the development environment with your SENDGRID_API_KEY (more info here), for example:

echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
echo "sendgrid.env" >> .gitignore
source ./sendgrid.env

SendGrid also supports local environment file .env. Copy or rename .env_sample into .env and update SENDGRID_API_KEY with your key.

Windows

Temporarily set the environment variable(accessible only during the current cli session):

set SENDGRID_API_KEY=YOUR_API_KEY

Permanently set the environment variable(accessible in all subsequent cli sessions):

setx SENDGRID_API_KEY "YOUR_API_KEY"

Install Package

pip install sendgrid

Dependencies

Quick Start

Hello Email

The following is the minimum needed code to send an email with the /mail/send Helper (here is a full example):

With Mail Helper Class

import sendgrid
import os
from sendgrid.helpers.mail import *

sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
from_email = Email("[email protected]")
to_email = To("[email protected]")
subject = "Sending with SendGrid is Fun"
content = Content("text/plain", "and easy to do anywhere, even with Python")
mail = Mail(from_email, to_email, subject, content)
response = sg.client.mail.send.post(request_body=mail.get())
print(response.status_code)
print(response.body)
print(response.headers)

The Mail constructor creates a personalization object for you. Here is an example of how to add it.

Without Mail Helper Class

The following is the minimum needed code to send an email without the /mail/send Helper (here is a full example):

import sendgrid
import os

sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
data = {
  "personalizations": [
    {
      "to": [
        {
          "email": "[email protected]"
        }
      ],
      "subject": "Sending with SendGrid is Fun"
    }
  ],
  "from": {
    "email": "[email protected]"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "and easy to do anywhere, even with Python"
    }
  ]
}
response = sg.client.mail.send.post(request_body=data)
print(response.status_code)
print(response.body)
print(response.headers)

General v3 Web API Usage (With Fluent Interface)

import sendgrid
import os

sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
response = sg.client.suppression.bounces.get()
print(response.status_code)
print(response.body)
print(response.headers)

General v3 Web API Usage (Without Fluent Interface)

import sendgrid
import os

sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
response = sg.client._("suppression/bounces").get()
print(response.status_code)
print(response.body)
print(response.headers)

Processing Inbound Email

Please see our helper for utilizing our Inbound Parse webhook.

Usage

Use Cases

Examples of common API use cases, such as how to send an email with a transactional template.

Announcements

Please see our announcement regarding breaking changes. Your support is appreciated!

All updates to this library are documented in our CHANGELOG and releases. You may also subscribe to email release notifications for releases and breaking changes.

How to Contribute

We encourage contribution to our libraries (you might even score some nifty swag), please see our CONTRIBUTING guide for details.

Quick links:

Troubleshooting

Please see our troubleshooting guide for common library issues.

About

sendgrid-python is maintained and funded by Twilio SendGrid, Inc. The names and logos for sendgrid-python are trademarks of Twilio SendGrid, Inc.

If you need help installing or using the library, please check the Twilio SendGrid Support Help Center.

If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!

License

The MIT License (MIT)

Comments
  • Proper MIMEMultipart determination for smtp

    Proper MIMEMultipart determination for smtp

    For compatibility with most email clients, you cannot simply detail the message MIME as a MIMEMultipart-Alternative if you have embedded images and attachments for view within HTML. MIMEMultipart-Related is the correct format, per http://tools.ietf.org/html/rfc2387.

    I have tested this with GMail, Thunderbird and Mail.app (Mac client), and it seems to work, whereas the current code will simply display my image attachment and none of the HMTL in Mail.app and Thunderbird.

    opened by vhmth 19
  • Python style fixes

    Python style fixes

    Checklist

    • [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [x] I have read the [Contribution Guide] and my PR follows them.
    • [x] I updated my branch with the master branch.
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [x] I have added necessary documentation about the functionality in the appropriate .md file
    • [x] I have added in line documentation to the code I modified

    Short description of what this PR does:

    • Cleans up Mail helper: reduces line count, uses Pythonic defaults
    • See commit notes for categories of fixes.

    These things were just bugging me a bit. There's probably a "terser is better" or something in the Python Zen.

    Note: I think existing tests should cover this since I didn't change any functionality, but I'll let Codecov yell at me if not. Tests pass with tox.

    status: code review request difficulty: medium 
    opened by gabrielkrell 15
  • Add Changelog script

    Add Changelog script

    Resolves #693

    Checklist

    • [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [x] I have read the [Contribution Guide] and my PR follows them.
    • [x] I updated my branch with the master branch.
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [ ] I have added necessary documentation about the functionality in the appropriate .md file
    • [x] I have added in line documentation to the code I modified

    Short description of what this PR does:

    • This PR introduces a generate_changelog.sh script that should take the newest PRs that have not been part of the latest release and creates an entry for them in the CHANGELOG.md file.
    • This uses the free, unauthenticated Github api to get PR titles. I felt like this was okay since it was the simplest solution and they allow 60 requests per hour this way.

    Example usage and output:

    ./generate_changelog.sh -v 6.0.0 -t 59077e7424629898d6554bc6a0ddcbd768901ae2
    Getting title of PR #656
    Getting title of PR #636
    Getting title of PR #628
    Getting title of PR #613
    Getting title of PR #619
    Getting title of PR #616
    Getting title of PR #611
    Successfully wrote to CHANGELOG.md
    

    diff

    diff --git a/CHANGELOG.md b/CHANGELOG.md
    index dd2334b..ad57211 100644
    --- a/CHANGELOG.md
    +++ b/CHANGELOG.md
    @@ -1,5 +1,15 @@
     # Change Log
     All notable changes to this project will be documented in this file.
    +## [6.0.0] - 2018-10-19 ##
    +### Added
    +- [PR #656](https://github.com/sendgrid/sendgrid-python/pull/656): Fix helper mail_example redirection link
    +- [PR #636](https://github.com/sendgrid/sendgrid-python/pull/636): Fix broken link for mail example
    +- [PR #628](https://github.com/sendgrid/sendgrid-python/pull/628): Update README
    +- [PR #613](https://github.com/sendgrid/sendgrid-python/pull/613): Update README.md by including email
    +- [PR #619](https://github.com/sendgrid/sendgrid-python/pull/619): Fix format of dependency `pytest`
    +- [PR #616](https://github.com/sendgrid/sendgrid-python/pull/616): Fix typos
    +- [PR #611](https://github.com/sendgrid/sendgrid-python/pull/611): fixes #610
    +
     
     ## [5.6.0] - 2018-08-20 ##
     ### Added
    

    If you have questions, please send an email to SendGrid, or file a GitHub Issue in this repository.

    status: work in progress difficulty: hard type: twilio enhancement 
    opened by PatOConnor43 13
  • feat: Support for AMP HTML Email

    feat: Support for AMP HTML Email

    I acknowledge that my contributions will be made under the same open-source license that the open-source project is provided under

    Adds support for sending AMP HTML email

    • Added third mime type -> text/x-amp-html
    • Send AMP HTML email just like normal html/plain email

    Resolves

    • Fixes #940
    • Fixes #850

    Checklist

    • [x] I acknowledge that all my contributions will be made under the project's license
    • [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [x] I have read the Contribution Guidelines and my PR follows them
    • [x] I have titled the PR appropriately
    • [x] I have updated my branch with the main branch
    • [x] I have added tests that prove my fix is effective or that my feature works
    • [x] I have added the necessary documentation about the functionality in the appropriate .md file
    • [x] I have added inline documentation to the code I modified
    type: community enhancement status: waiting for feedback 
    opened by modernwarfareuplink 10
  • Separate Attribution links in CoC #671

    Separate Attribution links in CoC #671

    Signed-off-by: Skchoudhary [email protected]

    Fixes # 671

    Checklist

    • [ ] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [X] I have read the [Contribution Guide] and my PR follows them.
    • [X] I updated my branch with the master branch.
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [ ] I have added necessary documentation about the functionality in the appropriate .md file
    • [ ] I have added in line documentation to the code I modified

    Short description of what this PR does:

    • separate the link for Open Source Initiative General Code of Conduct and Apache Code of Conduct to appear on the different line.

    If you have questions, please send an email to SendGrid, or file a GitHub Issue in this repository.

    difficulty: easy type: docs update status: waiting for feedback 
    opened by Skchoudhary 10
  • Update CONTRIBUTING.md to add python version 3.6

    Update CONTRIBUTING.md to add python version 3.6

    Fixes #657

    Checklist

    • [X] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [X] I have read the [Contribution Guide] and my PR follows them.
    • [X] I updated my branch with the master branch.
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [X] I have added necessary documentation about the functionality in the appropriate .md file
    • [ ] I have added in line documentation to the code I modified

    Short description of what this PR does:

    • Update CONTRIBUTING.md to keep instructions updated according to commands to test project

    If you have questions, please send an email to SendGrid, or file a GitHub Issue in this repository.

    type: bug difficulty: easy status: waiting for feedback 
    opened by mosesmeirelles 10
  • docs: Updated link to direct to #L9

    docs: Updated link to direct to #L9

    @misterdorm The link to /mail/send Helper looked fine. Please provide details as to where it should direct to.

    Fixes #633

    Checklist

    • [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [x] I have read the [Contribution Guide] and my PR follows them.
    • [x] I updated my branch with the master branch.
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [ ] I have added necessary documentation about the functionality in the appropriate .md file
    • [ ] I have added in line documentation to the code I modified

    Short description of what this PR does:

    • Made changes to #633

    If you have questions, please send an email to SendGrid, or file a GitHub Issue in this repository.

    difficulty: easy type: docs update status: waiting for feedback 
    opened by vinayak42 9
  • Adding events consumer which provides an example of working with email events

    Adding events consumer which provides an example of working with email events

    Resolves #649

    Checklist

    • [ ] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [ ] I have read the [Contribution Guide] and my PR follows them.
    • [ ] I updated my branch with the master branch.
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [ ] I have added necessary documentation about the functionality in the appropriate .md file
    • [ ] I have added in line documentation to the code I modified

    Short description of what this PR does:

    This PR adds

    • A Dockerized Flask app which provides an example of working with email events
    • A readme with guides for
      • Deploying locally with test data
      • Deploying locally with real data (using ngrok)
      • Deploying to Heroku

    This repo already contains a Procfile for the email ingress example, so I've suggested copying the events/ dir into a new repo on the users computer as part of the Heroku deploy to keep them separate.

    status: invalid difficulty: very hard type: twilio enhancement 
    opened by Taiters 9
  • Adds support for dynamic template data in personalizations

    Adds support for dynamic template data in personalizations

    Checklist

    • [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [x] I have read the [Contribution Guide] and my PR follows them.
    • [x] I updated my branch with the master branch.
    • [x] I have added tests that prove my fix is effective or that my feature works
    • [x] I have added necessary documentation about the functionality in the appropriate .md file
    • [x] I have added in line documentation to the code I modified

    Short description of what this PR does:

    Adds support for dynamic templates

    Fixes #591

    type: community enhancement status: work in progress difficulty: medium 
    opened by 3lnc 9
  • Initial version of code for supporting API rate limiting - WIP

    Initial version of code for supporting API rate limiting - WIP

    This PR is for initial code review and is still WIP. Will add more commits based on the feedback and answers from maintainers for few of my questions.

    Fixes #249

    • Added variables rate_limit_retry, rate_limit_sleep, RATE_LIMIT_RESPONSE_CODE in the constructor of SendGridAPIClient class.
    • Added method attempt in the class SendGridAPIClient
    • Added initial test file named test_rate_limit.py which calls attempt method.

    @thinkingserious I had a couple of questions while implementing and put up those questions as single line comments in the code - I hope to get advise or answers to those questions

    Thanks

    difficulty: medium status: waiting for feedback 
    opened by waseem18 9
  • Update docstrings/pydoc/help (#170)

    Update docstrings/pydoc/help (#170)

    Add docstrings in main package, helpers. Now things will show up nicely when people show documentation in their editor, use help, or use pydoc to browse the documentation in HTML form.

    Downside: much of the Mail helper docs are copied from the v3 docs, which isn't great for maintainability. I think it'd be too unapproachable just to say "read the docs", and linking docs updates to these docstrings would be a lot of work for the rewards. Maybe a future automation candidate though :)

    Example output:

    Pop-up docs in editors: image

    pydoc HTML: image

    Package-level help:

    >>> import sendgrid
    >>> help(sendgrid)
    Help on package sendgrid:
    
    NAME
        sendgrid
    
    DESCRIPTION
        This library allows you to quickly and easily use the SendGrid Web API v3 via
        Python.
    
        For more information on this library, see the README on Github.
            http://github.com/sendgrid/sendgrid-python
        For more information on the SendGrid v3 API, see the v3 docs:
            http://sendgrid.com/docs/API_Reference/api_v3.html
        For the user guide, code examples, and more, visit the main docs page:
            http://sendgrid.com/docs/index.html
    
        Available subpackages
        ---------------------
        helpers
            Modules to help with common tasks.
    
    PACKAGE CONTENTS
        helpers (package)
        sendgrid
        version
    -- More  --
    

    And individual classes:

    >>> from sendgrid.helpers.mail import Mail
    >>> help(Mail)
    Help on class Mail in module sendgrid.helpers.mail.mail:
    
    class Mail(builtins.object)
     |  A request to be sent with the SendGrid v3 Mail Send API (v3/mail/send).
     |
     |  Use get() to get the request body.
     |
     |  Methods defined here:
    -- More  --
    
    status: code review request difficulty: hard 
    opened by gabrielkrell 9
  • Add Python 3.11 to the testing

    Add Python 3.11 to the testing

    Fixes

    A short description of what this PR does.

    Checklist

    • [x] I acknowledge that all my contributions will be made under the project's license
    • [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [ ] I have read the Contribution Guidelines and my PR follows them
    • [ ] I have titled the PR appropriately
    • [x] I have updated my branch with the main branch
    • [x] I have added tests that prove my fix is effective or that my feature works
    • [ ] I have added the necessary documentation about the functionality in the appropriate .md file
    • [ ] I have added inline documentation to the code I modified

    If you have questions, please file a support ticket.

    opened by cclauss 0
  • docs: Update webhook auth docstring

    docs: Update webhook auth docstring

    Fixes

    The verify_signature method returns False if the event payload is decoded using utf-8 and special characters exist, such as "é". The payload must be decoded using latin-1 to successfully pass authorization in these situations.

    Checklist

    • [x] I acknowledge that all my contributions will be made under the project's license
    • [x] I have made a material change to the repo (functionality, testing, spelling, grammar)
    • [x] I have read the Contribution Guidelines and my PR follows them
    • [x] I have titled the PR appropriately
    • [x] I have updated my branch with the main branch
    • [x] I have added tests that prove my fix is effective or that my feature works
    • [x] I have added the necessary documentation about the functionality in the appropriate .md file
    • [x] I have added inline documentation to the code I modified

    If you have questions, please file a support ticket, or create a GitHub Issue in this repository.

    type: community enhancement type: docs update status: ready for deploy 
    opened by jpclark6 0
Releases(6.9.7)
Owner
Twilio SendGrid
Official open source libraries - send emails and integrate with our APIs fast.
Twilio SendGrid
MusicBot is the original Discord music bot written for Python 3.5+, using the discord.py library

The original MusicBot for Discord (formerly SexualRhinoceros/MusicBot)

Just Some Bots 2.9k Jan 02, 2023
通过GitHub的actions 自动采集节点 生成订阅信息

VmessActions 通过GitHub的actions 自动采集节点 自动生成订阅信息 订阅内容自动更新再仓库的 clash.yml 和 v2ray.txt 中 然后PC端/手机端根据自己的软件支持的格式,订阅对应的链接即可

skywolf627 372 Jan 04, 2023
An API that uses NLP and AI to let you predict possible diseases and symptoms based on a prompt of what you're feeling.

Disease detection API for MediSearch An API that uses NLP and AI to let you predict possible diseases and symptoms based on a prompt of what you're fe

Sebastian Ponce 1 Jan 15, 2022
Hasan Can Kaya - Konusanlar Ticket Notifier

Hasan Can Kaya - Konusanlar Ticket Notifier This script sends a notification to any telegram chat/group/channel when added a new available ticket to b

omer citak 3 Jan 31, 2022
This will create new discord accounts and add them to your server

Discord-Botter This tool will create new discord accounts add them to your server, this tool needs a captcha api like capmonster.cloud or anti-captcha

Shahzain 27 Nov 30, 2022
CDBEC: Catware DataBase Encryption Client

CDBEC: Catware DataBase Encryption Client Описание CDBEC - клиент для создания, просмотра и редактирования .db-catencrypted списков, шифруемых при пом

Catware-Foundation 2 Nov 03, 2022
A python wrapper for the mangadex API V5. Work in progress

mangadex A python wrapper for the mangadex API V5. It uses the requests library and all the aditional arguments can be viewed in the Official Mangadex

Eduardo Ceja 27 Dec 14, 2022
Fully asynchronous trace.moe API wrapper

AioMoe Fully asynchronous trace.moe API wrapper Installation You can install the stable version from PyPI: $ pip install aiomoe Or get it from github

2 Jun 26, 2022
Azure DevOps Extension for Azure CLI

Azure DevOps Extension for Azure CLI The Azure DevOps Extension for Azure CLI adds Pipelines, Boards, Repos, Artifacts and DevOps commands to the Azur

1 Nov 03, 2021
WallAlley.bot is an open source and free to use financial discord bot originaly build for WallAlley server's community

WallAlley.bot About WallAlley.bot is an open source and free to use financial discord bot originaly build for WallAlley server's community. All data a

Mohammad KHADDAN 1 Jan 22, 2022
Slack Developer Kit for Python

Python Slack SDK The Slack platform offers several APIs to build apps. Each Slack API delivers part of the capabilities from the platform, so that you

SlackAPI 3.5k Jan 02, 2023
A mood based crypto tracking application.

Crypto Bud - API A mood based crypto tracking application. The main repository is private. I am creating the API before I connect everything to the ma

Krishnasis Mandal 1 Oct 23, 2021
Trellox Tool is written in Python3 and designed to pull and list Trello boards.

TrelloX Trellox Tool is written in Python3 and designed to list and pull Trello boards. It can be used by penetration testers/bug bounty hunters to de

Ali Fathi Ali Sawehli 1 Dec 05, 2021
A Python Script to automate searching of available vaccination centers in the city and hence booking

Cowin Vaccine Availability Notifier Cowin Vaccine Availability Notifier takes your City or PIN code as an input and automatically notifies you via ema

Jayesh Padhiar 7 Sep 05, 2021
LoL 台版10周年活動自動輸入邀請碼

LoLTW_10Year_88Event LoLTW 8.8 周年慶 邀請碼自動輸入 設定 在 LoLTW_10Year_88Evnet.exe 的位置建立一個檔案 .env,內容如下 Bahamut_Discussion = https://forum.gamer.com.tw/C.php?bsn

古丁丁 5 Dec 13, 2021
Simple tool to gather domains from crt.sh using the organization name

Domain Collector: _ _ ___ _ _ _ __| | ___ _ __ ___ __ _(_)_ __ / __\___ | |

Cyber Guy 63 Dec 24, 2022
A Python API to retrieve and read MLB GameDay data

mlbgame mlbgame is a Python API to retrieve and read MLB GameDay data. mlbgame works with real time data, getting information as games are being playe

Zach Panzarino 493 Dec 13, 2022
A telegram smoot and high quality music player bot.

▪︎ Music Player ▪︎ A smooth telegram music bot with high quality songs ■ [Features] • Fast Starts streaming your inputs while downloading and converti

Simple Boy 3 Feb 05, 2022
Demonstrate how GitHub OIDC token getting should be included in boto3

boto3 should add direct support for AssumeRoleWithWebIdentity for GitHub Actions There is a aws-actions/configure-aws-credentials action that will get

Ben Kehoe 11 Aug 29, 2022
A python based all-in-one tool for Google Drive

gdrive-tools A python based all-in-one tool for Google Drive Uses For Gdrive-Tools ✓ generate SA ✓ Add the SA and Add them to TD automatically ✓ Gener

XcodersHub 32 Feb 09, 2022