Skip to contentSkip to navigationSkip to topbar
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.

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 h2
4
* ALPN, offering http/1.1
5
* successfully set certificate verify locations:
6
* CAfile: /etc/ssl/cert.pem
7
* CApath: none
8
* (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-SHA256
19
...
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.

1
curl 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.

1
SSL handshake has read 5793 bytes and written 322 bytes
2
...
3
SSL-Session:
4
Protocol : TLSv1.2
5
Cipher : ECDHE-RSA-AES256-GCM-SHA384
6
...

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)

1
using SendGrid;
2
using SendGrid.Helpers.Mail;
3
4
5
var apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY");
6
7
8
// Override host with TLS 1.2+ endpoint
9
var host = "https://tls12.api.sendgrid.com";
10
var client = new SendGridClient(apiKey, host);
11
12
13
var from = new EmailAddress("sender@example.com", "Sender");
14
var subject = "Sending with Twilio SendGrid is Fun";
15
var to = new EmailAddress("recipient@example.com", "Recipient");
16
var plainTextContent = "and easy to do anywhere with C#.";
17
var htmlContent = "<strong>and easy to do anywhere with C#</strong>.";
18
19
20
var message = MailHelper.CreateSingleEmail(from, to, subject, plainTextContent, htmlContent);
21
var response = await client.SendEmailAsync(message);
22
23
24
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)

1
package main
2
3
import (
4
"fmt"
5
"log"
6
"os"
7
8
"github.com/sendgrid/sendgrid-go"
9
"github.com/sendgrid/sendgrid-go/helpers/mail"
10
)
11
12
// Override default client to accept TLS 1.2 test host
13
func NewSendClient(key string, host string) *sendgrid.Client {
14
request := sendgrid.GetRequest(key, "/v3/mail/send", host)
15
request.Method = "POST"
16
return &sendgrid.Client{Request: request}
17
}
18
19
func main() {
20
from := mail.NewEmail("Sender", "sender@example.com")
21
subject := "Sending with Twilio SendGrid is Fun"
22
to := mail.NewEmail("Recipient", "recipient@example.com")
23
plainTextContent := "and easy to do anywhere with Go."
24
htmlContent := "<strong>and easy to do anywhere with Go.</strong>"
25
message := mail.NewSingleEmail(from, subject, to, plainTextContent, htmlContent)
26
// Use TLS 1.2+ endpoint as host
27
client := NewSendClient(os.Getenv("SENDGRID_API_KEY"), "https://tls12.api.sendgrid.com")
28
29
30
response, err := client.Send(message)
31
if err != nil {
32
log.Println(err)
33
} else {
34
fmt.Println(response.StatusCode)
35
fmt.Println(response.Headers)
36
}
37
}

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

1
import com.sendgrid.*;
2
import java.io.IOException;
3
4
5
public class Example {
6
public static void main(String[] args) throws IOException {
7
Email from = new Email("sender@example.com");
8
String subject = "Sending with Twilio SendGrid is Fun";
9
Email to = new Email("recipient@example.com");
10
Content content = new Content("text/plain", "and easy to do anywhere with Java.");
11
Mail mail = new Mail(from, subject, to, content);
12
13
14
SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
15
// Override host with TLS 1.2+ endpoint
16
sg.setHost("tls12.api.sendgrid.com");
17
Request request = new Request();
18
try {
19
request.setMethod(Method.POST);
20
request.setEndpoint("mail/send");
21
request.setBody(mail.build());
22
Response response = sg.api(request);
23
System.out.println(response.getStatusCode());
24
System.out.println(response.getBody());
25
System.out.println(response.getHeaders());
26
} catch (IOException ex) {
27
throw ex;
28
}
29
}
30
}

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

1
const sgMail = require("@sendgrid/mail");
2
const client = require("@sendgrid/client");
3
4
5
// Override baseUrl to use TLS 1.2+ test endpoint
6
client.setApiKey(process.env.SENDGRID_API_KEY);
7
client.setDefaultRequest("baseUrl", "https://tls12.api.sendgrid.com");
8
sgMail.setClient(client);
9
10
11
const msg = {
12
to: "recipient@example.com",
13
from: "sender@example.com",
14
subject: "Sending with Twilio SendGrid is Fun",
15
text: "and easy to do anywhere with NodeJS.",
16
html: "<strong>and easy to do anywhere with NodeJS.</strong>",
17
};
18
19
20
sgMail.send(msg).then(
21
() => {},
22
(error) => {
23
console.error(error);
24
25
26
if (error.response) {
27
console.error(error.response.body);
28
}
29
}
30
);

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

1
<?php
2
3
declare(strict_types=1);
4
5
require 'vendor/autoload.php';
6
7
use \SendGrid\Mail\Mail;
8
9
$email = new Mail();
10
// Replace the email address and name with your verified sender
11
$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 recipient
17
$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+ host
26
$sendgrid = new \SendGrid(
27
getenv('SENDGRID_API_KEY'),
28
['host' => 'https://tls12.api.sendgrid.com']
29
);
30
try {
31
$response = $sendgrid->send($email);
32
printf("Response status: %d\n\n", $response->statusCode());
33
34
35
$headers = array_filter($response->headers());
36
echo "Response Headers\n\n";
37
foreach ($headers as $header) {
38
echo '- ' . $header . "\n";
39
}
40
} catch (Exception $e) {
41
echo 'Caught exception: ' . $e->getMessage() . "\n";
42
}

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

1
import sendgrid
2
import os
3
from sendgrid.helpers.mail import *
4
5
# Set host to the TLS 1.2+ test endpoint
6
sg = sendgrid.SendGridAPIClient(
7
host='https://tls12.api.sendgrid.com',
8
api_key=os.environ.get('SENDGRID_API_KEY')
9
)
10
from_email = Email("sender@example.com")
11
to_email = To("recipient@example.com")
12
subject = "Sending with SendGrid is Fun"
13
content = Content("text/plain", "and easy to do anywhere with Python.")
14
mail = Mail(from_email, to_email, subject, content)
15
response = sg.client.mail.send.post(request_body=mail.get())
16
print(response.status_code)
17
print(response.body)
18
print(response.headers)

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

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

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

1
SSL handshake has read 5779 bytes and written 322 bytes
2
...
3
SSL-Session:
4
Protocol : TLSv1.2
5
Cipher : ECDHE-RSA-AES256-GCM-SHA384
6
...

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.