Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Support for TLS 1.2


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(link takes you to an external page) 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.


Test your connection

test-your-connection page anchor

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.

(warning)

Warning

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


Test with curl

test-with-curl page anchor

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.


_10
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.


_20
* Trying 167.89.118.69:443...
_20
* Connected to tls12.api.sendgrid.com (167.89.118.69) port 443 (#0)
_20
* ALPN, offering h2
_20
* ALPN, offering http/1.1
_20
* successfully set certificate verify locations:
_20
* CAfile: /etc/ssl/cert.pem
_20
* CApath: none
_20
* (304) (OUT), TLS handshake, Client hello (1):
_20
* (304) (IN), TLS handshake, Server hello (2):
_20
* TLSv1.2 (IN), TLS handshake, Certificate (11):
_20
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
_20
* TLSv1.2 (IN), TLS handshake, Server finished (14):
_20
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
_20
* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1):
_20
* TLSv1.2 (OUT), TLS handshake, Finished (20):
_20
* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1):
_20
* TLSv1.2 (IN), TLS handshake, Finished (20):
_20
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
_20
...
_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.


_10
curl https://tls12.api.sendgrid.com/v3/mail/send \
_10
--tlsv1.2 \
_10
--header 'Authorization: Bearer <<YOUR API KEY>>' \
_10
--header 'Content-Type: application/json' \
_10
--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.


_10
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.


_10
SSL handshake has read 5793 bytes and written 322 bytes
_10
...
_10
SSL-Session:
_10
Protocol : TLSv1.2
_10
Cipher : ECDHE-RSA-AES256-GCM-SHA384
_10
...

Test with Windows Server

test-with-windows-server page anchor

Beginning with Windows Server 2012, TLS 1.2 is enabled by default(link takes you to an external page). 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(link takes you to an external page) for help enabling and configuring TLS on Windows Server.

Test with Twilio SendGrid helper libraries

test-with-twilio-sendgrid-helper-libraries page anchor

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.

C#/.Net

cnet page anchor

Library repository: https://github.com/sendgrid/sendgrid-csharp(link takes you to an external page)


_25
using SendGrid;
_25
using SendGrid.Helpers.Mail;
_25
_25
_25
var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
_25
_25
_25
// Override host with TLS 1.2+ endpoint
_25
var host = "https://tls12.api.sendgrid.com";
_25
var client = new SendGridClient(apiKey, host);
_25
_25
_25
var from = new EmailAddress("sender@example.com", "Sender");
_25
var subject = "Sending with Twilio SendGrid is Fun";
_25
var to = new EmailAddress("recipient@example.com", "Recipient");
_25
var plainTextContent = "and easy to do anywhere with C#.";
_25
var htmlContent = "<strong>and easy to do anywhere with C#</strong>.";
_25
_25
_25
var message = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
_25
var response = await client.SendEmailAsync(message);
_25
_25
_25
Console.WriteLine($"Response status code: {response.StatusCode}");
_25
Console.WriteLine($"Response body: {await response.Body.ReadAsStringAsync()}");

Library repository: https://github.com/sendgrid/sendgrid-go(link takes you to an external page)


_37
package main
_37
_37
import (
_37
"fmt"
_37
"log"
_37
"os"
_37
_37
"github.com/sendgrid/sendgrid-go"
_37
"github.com/sendgrid/sendgrid-go/helpers/mail"
_37
)
_37
_37
// Override default client to accept TLS 1.2 test host
_37
func NewSendClient(key string, host string) *sendgrid.Client {
_37
request := sendgrid.GetRequest(key, "/v3/mail/send", host)
_37
request.Method = "POST"
_37
return &sendgrid.Client{Request: request}
_37
}
_37
_37
func main() {
_37
from := mail.NewEmail("Sender", "sender@example.com")
_37
subject := "Sending with Twilio SendGrid is Fun"
_37
to := mail.NewEmail("Recipient", "recipient@example.com")
_37
plainTextContent := "and easy to do anywhere with Go."
_37
htmlContent := "<strong>and easy to do anywhere with Go.</strong>"
_37
message := mail.NewSingleEmail(from, subject, to, plainTextContent, htmlContent)
_37
// Use TLS 1.2+ endpoint as host
_37
client := NewSendClient(os.Getenv("SENDGRID_API_KEY"), "https://tls12.api.sendgrid.com")
_37
_37
_37
response, err := client.Send(message)
_37
if err != nil {
_37
log.Println(err)
_37
} else {
_37
fmt.Println(response.StatusCode)
_37
fmt.Println(response.Headers)
_37
}
_37
}

Library repository: https://github.com/sendgrid/sendgrid-java(link takes you to an external page)


_30
import com.sendgrid.*;
_30
import java.io.IOException;
_30
_30
_30
public class Example {
_30
public static void main(String[] args) throws IOException {
_30
Email from = new Email("sender@example.com");
_30
String subject = "Sending with Twilio SendGrid is Fun";
_30
Email to = new Email("recipient@example.com");
_30
Content content = new Content("text/plain", "and easy to do anywhere with Java.");
_30
Mail mail = new Mail(from, subject, to, content);
_30
_30
_30
SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
_30
// Override host with TLS 1.2+ endpoint
_30
sg.setHost("tls12.api.sendgrid.com");
_30
Request request = new Request();
_30
try {
_30
request.setMethod(Method.POST);
_30
request.setEndpoint("mail/send");
_30
request.setBody(mail.build());
_30
Response response = sg.api(request);
_30
System.out.println(response.getStatusCode());
_30
System.out.println(response.getBody());
_30
System.out.println(response.getHeaders());
_30
} catch (IOException ex) {
_30
throw ex;
_30
}
_30
}
_30
}

Library repository: https://github.com/sendgrid/sendgrid-nodejs(link takes you to an external page)


_30
const sgMail = require("@sendgrid/mail");
_30
const client = require("@sendgrid/client");
_30
_30
_30
// Override baseUrl to use TLS 1.2+ test endpoint
_30
client.setApiKey(process.env.SENDGRID_API_KEY);
_30
client.setDefaultRequest("baseUrl", "https://tls12.api.sendgrid.com");
_30
sgMail.setClient(client);
_30
_30
_30
const msg = {
_30
to: "recipient@example.com",
_30
from: "sender@example.com",
_30
subject: "Sending with Twilio SendGrid is Fun",
_30
text: "and easy to do anywhere with NodeJS.",
_30
html: "<strong>and easy to do anywhere with NodeJS.</strong>",
_30
};
_30
_30
_30
sgMail.send(msg).then(
_30
() => {},
_30
(error) => {
_30
console.error(error);
_30
_30
_30
if (error.response) {
_30
console.error(error.response.body);
_30
}
_30
}
_30
);

Library repository: https://github.com/sendgrid/sendgrid-php(link takes you to an external page)


_42
<?php
_42
_42
declare(strict_types=1);
_42
_42
require 'vendor/autoload.php';
_42
_42
use \SendGrid\Mail\Mail;
_42
_42
$email = new Mail();
_42
// Replace the email address and name with your verified sender
_42
$email->setFrom(
_42
'sender@example.com',
_42
'Example Sender'
_42
);
_42
$email->setSubject('Sending with Twilio SendGrid is Fun');
_42
// Replace the email address and name with your recipient
_42
$email->addTo(
_42
'recipient@example.com',
_42
'Example Recipient'
_42
);
_42
$email->addContent(
_42
'text/html',
_42
'<strong>and easy to do anywhere with PHP.</strong>'
_42
);
_42
// Pass the SendGrid class an options array with the TLS 1.2+ host
_42
$sendgrid = new \SendGrid(
_42
getenv('SENDGRID_API_KEY'),
_42
['host' => 'https://tls12.api.sendgrid.com']
_42
);
_42
try {
_42
$response = $sendgrid->send($email);
_42
printf("Response status: %d\n\n", $response->statusCode());
_42
_42
_42
$headers = array_filter($response->headers());
_42
echo "Response Headers\n\n";
_42
foreach ($headers as $header) {
_42
echo '- ' . $header . "\n";
_42
}
_42
} catch (Exception $e) {
_42
echo 'Caught exception: ' . $e->getMessage() . "\n";
_42
}

Library repository: https://github.com/sendgrid/sendgrid-python(link takes you to an external page)


_18
import sendgrid
_18
import os
_18
from sendgrid.helpers.mail import *
_18
_18
# Set host to the TLS 1.2+ test endpoint
_18
sg = sendgrid.SendGridAPIClient(
_18
host='https://tls12.api.sendgrid.com',
_18
api_key=os.environ.get('SENDGRID_API_KEY')
_18
)
_18
from_email = Email("sender@example.com")
_18
to_email = To("recipient@example.com")
_18
subject = "Sending with SendGrid is Fun"
_18
content = Content("text/plain", "and easy to do anywhere with Python.")
_18
mail = Mail(from_email, to_email, subject, content)
_18
response = sg.client.mail.send.post(request_body=mail.get())
_18
print(response.status_code)
_18
print(response.body)
_18
print(response.headers)

Library repository: https://github.com/sendgrid/sendgrid-ruby(link takes you to an external page)


_14
require 'sendgrid-ruby'
_14
include SendGrid
_14
_14
from = SendGrid::Email.new(email: 'sender@example.com', name: "Sender")
_14
to = SendGrid::Email.new(email: 'recipient@example.com', name: "Recipient")
_14
subject = 'Sending with Twilio SendGrid is Fun'
_14
content = SendGrid::Content.new(type: 'text/html', value: 'and easy to do anywhere with Ruby.')
_14
mail = SendGrid::Mail.new(from, subject, to, content)
_14
_14
# Set host to TLS 1.2 test endpoint
_14
sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY'], host: 'https://tls12.api.sendgrid.com')
_14
response = sg.client.mail._('send').post(request_body: mail.to_json)
_14
puts response.status_code
_14
puts 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.

(warning)

Warning

Some ISPs block port 25. If your ISP blocks port 25, the test command on that port will timeout and fail.


_10
# Port 25 startTLS
_10
openssl s_client -connect tls12.smtp.sendgrid.net:25 -starttls smtp -tls1_2
_10
_10
# Port 465 SSL
_10
openssl 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.


_10
SSL handshake has read 5779 bytes and written 322 bytes
_10
...
_10
SSL-Session:
_10
Protocol : TLSv1.2
_10
Cipher : ECDHE-RSA-AES256-GCM-SHA384
_10
...

Test with Twilio SendGrid helper libraries

test-with-twilio-sendgrid-helper-libraries-2 page anchor

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.

  • Operating System SSL library
  • Application server security components
  • Network proxy
  • Firewall

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.

.Net SendGrid helper library

net-sendgrid-helper-library page anchor

Customers using the SendGrid C# helper library(link takes you to an external page) who are not able to connect with our TLS 1.2 endpoint are likely using an older version of the .Net framework(link takes you to an external page) 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.


Rate this page: