Twilio SendGrid will support TLS connections using only TLS 1.2 beginning June 5, 2023.
If you attempt to connect to Twilio SendGrid using TLS 1.0 or 1.1, the TLS handshake will fail, preventing you from establishing a connection with our APIs. Be sure you are using TLS 1.2 before June 5, 2023 to avoid interruptions to your email services.
We have provided HTTP and SMTP test endpoints that support only TLS 1.2 to help you prepare for this change. Use these endpoints to test your current environment. If your connection test fails, you may need to upgrade one or more layers of your infrastructure. See the "Components to check" section of this page for a list of components that may require updates.
To test your connection, you should make an HTTP or SMTP request — whichever matches your Twilio SendGrid integration — to one of the following test endpoints. Some options for making this connection are outlined in the next section. We have tried to be as comprehensive as possible with our examples. You do not need to read this entire document. You can skip directly to the testing method that matches your integration or testing preferences.
Your connection tests should come from your production environment. Testing from a local development environment may pick up support for TLS 1.2 from your local operating system, which does not indicate if your production environment is properly configured to support TLS 1.2.
Like the production Twilio SendGrid endpoints, the test HTTP endpoint is on the .com
top level domain (TLD) and the SMTP test endpoint is on the .net
TLD. If your test is failing, be sure you are using the correct test URL.
Test HTTP endpoint
tls12.api.sendgrid.com
Test SMTP endpoint
tls12.smtp.sendgrid.net
If you are able to make curl requests from your production environment, you can run the following command to verify a connection with our TLS 1.2 test endpoint.
curl https://tls12.api.sendgrid.com:443 --tlsv1.2 --verbose
If your connection is successful, you will see information about the TLS handshake and the message: Connection #0 to host tls12.api.sendgrid.com left intact
.
The following example shows a partial response from a successful connection. More information will be present in a complete response, which is represented by the "…
" in this example.
1* Trying 167.89.118.69:443...2* Connected to tls12.api.sendgrid.com (167.89.118.69) port 443 (#0)3* ALPN, offering h24* ALPN, offering http/1.15* successfully set certificate verify locations:6* CAfile: /etc/ssl/cert.pem7* CApath: none8* (304) (OUT), TLS handshake, Client hello (1):9* (304) (IN), TLS handshake, Server hello (2):10* TLSv1.2 (IN), TLS handshake, Certificate (11):11* TLSv1.2 (IN), TLS handshake, Server key exchange (12):12* TLSv1.2 (IN), TLS handshake, Server finished (14):13* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):14* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1):15* TLSv1.2 (OUT), TLS handshake, Finished (20):16* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1):17* TLSv1.2 (IN), TLS handshake, Finished (20):18* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA25619...20* Connection #0 to host tls12.api.sendgrid.com left intact
You can also use curl with your SendGrid API key to test your connection to our HTTP test endpoint and the Mail Send API. Please note that the email addresses are demos and you must update them to real email addresses to successfully send and receive messages.
1curl https://tls12.api.sendgrid.com/v3/mail/send \2--tlsv1.2 \3--header 'Authorization: Bearer <<YOUR API KEY>>' \4--header 'Content-Type: application/json' \5--data '{"personalizations": [{"to": [{"email": "recipient@example.com"}]}],"from": {"email": "sender@example.com"},"subject": "Hello, World!","content": [{"type": "text/plain", "value": "Hello from SendGrid!"}]}'
Unix-like systems, including Linux distributions and macOS, often have the openssl library available. You can test your connection using the following command.
openssl s_client -connect tls12.api.sendgrid.com:443 -tls1_2
A successful connection will return a large response that includes a certificate chain and server certificate. You should see a block labeled SSL-Session
with the TLSv1.2 protocol listed.
The following example shows a partial response from a successful connection. More information will be present in a complete response, which is represented by the "…
" in the example. All of this information will be below the certificate chain and server certificate in the response.
1SSL handshake has read 5793 bytes and written 322 bytes2...3SSL-Session:4Protocol : TLSv1.25Cipher : ECDHE-RSA-AES256-GCM-SHA3846...
Beginning with Windows Server 2012, TLS 1.2 is enabled by default. Windows Server 2008 has reached end of life, so your Windows Server is likely already supporting TLS 1.2 if you are keeping your systems up to date. See the Microsoft documentation for help enabling and configuring TLS on Windows Server.
The SendGrid HTTP helper libraries each offer a client that will set the host of your API requests for you. By default, the host is https://api.sendgrid.com
. You can modify the host to use the TLS 1.2 test URL, https://tls12.api.sendgrid.com
, to make a connection with our TLS 1.2 test endpoint.
The following samples show a request to the Mail Send endpoint at /v3/mail/send
. These code samples are modified from the samples provided in our helper library README files. Please see the helper library you are using for more library-specific documentation. Each library is linked just before its related code sample.
Please note that the email addresses are demos and you must update them to real email addresses to successfully send and receive messages.
Library repository: https://github.com/sendgrid/sendgrid-csharp
1using SendGrid;2using SendGrid.Helpers.Mail;345var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");678// Override host with TLS 1.2+ endpoint9var host = "https://tls12.api.sendgrid.com";10var client = new SendGridClient(apiKey, host);111213var from = new EmailAddress("sender@example.com", "Sender");14var subject = "Sending with Twilio SendGrid is Fun";15var to = new EmailAddress("recipient@example.com", "Recipient");16var plainTextContent = "and easy to do anywhere with C#.";17var htmlContent = "<strong>and easy to do anywhere with C#</strong>.";181920var message = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);21var response = await client.SendEmailAsync(message);222324Console.WriteLine($"Response status code: {response.StatusCode}");25Console.WriteLine($"Response body: {await response.Body.ReadAsStringAsync()}");
Library repository: https://github.com/sendgrid/sendgrid-go
1package main23import (4"fmt"5"log"6"os"78"github.com/sendgrid/sendgrid-go"9"github.com/sendgrid/sendgrid-go/helpers/mail"10)1112// Override default client to accept TLS 1.2 test host13func NewSendClient(key string, host string) *sendgrid.Client {14request := sendgrid.GetRequest(key, "/v3/mail/send", host)15request.Method = "POST"16return &sendgrid.Client{Request: request}17}1819func main() {20from := mail.NewEmail("Sender", "sender@example.com")21subject := "Sending with Twilio SendGrid is Fun"22to := mail.NewEmail("Recipient", "recipient@example.com")23plainTextContent := "and easy to do anywhere with Go."24htmlContent := "<strong>and easy to do anywhere with Go.</strong>"25message := mail.NewSingleEmail(from, subject, to, plainTextContent, htmlContent)26// Use TLS 1.2+ endpoint as host27client := NewSendClient(os.Getenv("SENDGRID_API_KEY"), "https://tls12.api.sendgrid.com")282930response, err := client.Send(message)31if err != nil {32log.Println(err)33} else {34fmt.Println(response.StatusCode)35fmt.Println(response.Headers)36}37}
Library repository: https://github.com/sendgrid/sendgrid-java
1import com.sendgrid.*;2import java.io.IOException;345public class Example {6public static void main(String[] args) throws IOException {7Email from = new Email("sender@example.com");8String subject = "Sending with Twilio SendGrid is Fun";9Email to = new Email("recipient@example.com");10Content content = new Content("text/plain", "and easy to do anywhere with Java.");11Mail mail = new Mail(from, subject, to, content);121314SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));15// Override host with TLS 1.2+ endpoint16sg.setHost("tls12.api.sendgrid.com");17Request request = new Request();18try {19request.setMethod(Method.POST);20request.setEndpoint("mail/send");21request.setBody(mail.build());22Response response = sg.api(request);23System.out.println(response.getStatusCode());24System.out.println(response.getBody());25System.out.println(response.getHeaders());26} catch (IOException ex) {27throw ex;28}29}30}
Library repository: https://github.com/sendgrid/sendgrid-nodejs
1const sgMail = require("@sendgrid/mail");2const client = require("@sendgrid/client");345// Override baseUrl to use TLS 1.2+ test endpoint6client.setApiKey(process.env.SENDGRID_API_KEY);7client.setDefaultRequest("baseUrl", "https://tls12.api.sendgrid.com");8sgMail.setClient(client);91011const msg = {12to: "recipient@example.com",13from: "sender@example.com",14subject: "Sending with Twilio SendGrid is Fun",15text: "and easy to do anywhere with NodeJS.",16html: "<strong>and easy to do anywhere with NodeJS.</strong>",17};181920sgMail.send(msg).then(21() => {},22(error) => {23console.error(error);242526if (error.response) {27console.error(error.response.body);28}29}30);
Library repository: https://github.com/sendgrid/sendgrid-php
1<?php23declare(strict_types=1);45require 'vendor/autoload.php';67use \SendGrid\Mail\Mail;89$email = new Mail();10// Replace the email address and name with your verified sender11$email->setFrom(12'sender@example.com',13'Example Sender'14);15$email->setSubject('Sending with Twilio SendGrid is Fun');16// Replace the email address and name with your recipient17$email->addTo(18'recipient@example.com',19'Example Recipient'20);21$email->addContent(22'text/html',23'<strong>and easy to do anywhere with PHP.</strong>'24);25// Pass the SendGrid class an options array with the TLS 1.2+ host26$sendgrid = new \SendGrid(27getenv('SENDGRID_API_KEY'),28['host' => 'https://tls12.api.sendgrid.com']29);30try {31$response = $sendgrid->send($email);32printf("Response status: %d\n\n", $response->statusCode());333435$headers = array_filter($response->headers());36echo "Response Headers\n\n";37foreach ($headers as $header) {38echo '- ' . $header . "\n";39}40} catch (Exception $e) {41echo 'Caught exception: ' . $e->getMessage() . "\n";42}
Library repository: https://github.com/sendgrid/sendgrid-python
1import sendgrid2import os3from sendgrid.helpers.mail import *45# Set host to the TLS 1.2+ test endpoint6sg = sendgrid.SendGridAPIClient(7host='https://tls12.api.sendgrid.com',8api_key=os.environ.get('SENDGRID_API_KEY')9)10from_email = Email("sender@example.com")11to_email = To("recipient@example.com")12subject = "Sending with SendGrid is Fun"13content = Content("text/plain", "and easy to do anywhere with Python.")14mail = Mail(from_email, to_email, subject, content)15response = sg.client.mail.send.post(request_body=mail.get())16print(response.status_code)17print(response.body)18print(response.headers)
Library repository: https://github.com/sendgrid/sendgrid-ruby
1require 'sendgrid-ruby'2include SendGrid34from = SendGrid::Email.new(email: 'sender@example.com', name: "Sender")5to = SendGrid::Email.new(email: 'recipient@example.com', name: "Recipient")6subject = 'Sending with Twilio SendGrid is Fun'7content = SendGrid::Content.new(type: 'text/html', value: 'and easy to do anywhere with Ruby.')8mail = SendGrid::Mail.new(from, subject, to, content)910# Set host to TLS 1.2 test endpoint11sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'], host: 'https://tls12.api.sendgrid.com')12response = sg.client.mail._('send').post(request_body: mail.to_json)13puts response.status_code14puts response.headers
Unix-like systems, including Linux distributions and MacOS, often have the openssl library available. You can test your connection with this library using the following commands.
Some ISPs block port 25. If your ISP blocks port 25, the test command on that port will timeout and fail.
1# Port 25 startTLS2openssl s_client -connect tls12.smtp.sendgrid.net:25 -starttls smtp -tls1_234# Port 465 SSL5openssl s_client -connect tls12.smtp.sendgrid.net:465 -tls1_2
A successful connection will return a large response that includes a certificate chain and server certificate. You should see a block labeled SSL-Session
with the TLSv1.2 protocol listed.
The following example shows a partial response from a successful connection. More information will be present in a complete response, which is represented by the "…
" in the example. All of this information will be below the certificate chain and server certificate in the response.
1SSL handshake has read 5779 bytes and written 322 bytes2...3SSL-Session:4Protocol : TLSv1.25Cipher : ECDHE-RSA-AES256-GCM-SHA3846...
The SendGrid SMTP helper libraries each provide a way to build a SendGrid X-SMTPAPI header. The X-SMTPAPI header makes it possible to schedule your sends, add categories, and otherwise modify your messages when using the SendGrid SMTP service.
To send your email via SMTP, you may be using one of several SMTP libraries. Some languages, such as Python, take a batteries-included approach and provide an SMTP package as part of their standard libraries. Other languages, such as NodeJS, rely on third-party packages for SMTP support.
When reviewing your code, you will need to look at your SMTP library to test with our TLS 1.2 endpoint rather than the Twilio SendGrid helper library itself. Your use of the Twilio SendGrid SMTP libraries will not require any modifications.
By default, Twilio SendGrid's SMTP host is smtp.sendgrid.net
. You can modify the host to use the TLS 1.2 test URL, tls12.smtp.sendgrid.net
, wherever the host is set in your SMTP library.
For your convenience, the Twilio SendGrid SMTP helper libraries are linked below.
If your connection test failed, there are several layers of your infrastructure to check.
Often, you need only to upgrade your operating system's SSL libraries. However, it's possible you will need to update your HTTP client's or helper library's underlying dependencies.
Because every software system is different, you will need to consult with your internal teams to understand the best approach for upgrading your system. We hope the above list provides a good starting point.
Customers using the SendGrid C# helper library who are not able to connect with our TLS 1.2 endpoint are likely using an older version of the .Net framework that they will need to update. See the following Microsoft documentation for more information.
Once you have upgraded the necessary layers of your infrastructure, attempt to connect with TLS 1.2 test endpoints as detailed in the "Test your connection" section of this document. You should now be able to successfully connect.
Twilio SendGrid's systems already support TLS 1.2, so you can connect to Twilio SendGrid's other endpoints immediately following updates to your own systems.