How to Send an SMTP Email

You can also send email with the UI and with the API.

What is SMTP?

Simple Mail Transfer Protocol (SMTP) is a quick and easy way to send email from one server to another. SendGrid provides an SMTP service that allows you to deliver your email via our servers instead of your own client or server. This means you can count on SendGrid's delivery at scale for your SMTP needs.

SendGrid’s SMTP API also allows you to specify custom email handling instructions using a JSON encoded list called the X-SMTPAPI header. The X-SMTPAPI header is parsed by SendGrid to modify your message in the ways you specify.

For a deeper dive into what SMTP is, the benefits of sending an email with SMTP, and how SendGrid can help, see the SMTP Service Crash Course on our blog.

Sending a test SMTP email with Telnet

This page will help you send a first test message using Telnet. Once you complete this process, you will be better prepared to explore and build messages using the X-SMTPAPI header.

Prerequisites

Be sure to perform the following prerequisites to complete this tutorial.

  1. Sign up for a SendGrid account
  2. Create and store a SendGrid API key with full access "Mail Send" permissions.
  3. Verify your Sender Identity
  4. Open your terminal, also commonly referred to as a command prompt, or command line. You'll use the terminal to encode your API key and input the commands that initiate a Telnet connection.

In the following code samples, greater than and less than symbol are wrapped around placeholder values (e.g., <YOUR_API_KEY>). You should replace the greater than and less than symbols and the text inside them with an actual value. For example, echo -n '<YOUR_API_KEY>' | openssl base64 will become echo -n 'SG.someactualkey' | openssl base64 if your API key is SG.someactualkey.

In some cases you will see two sets of greater than and less than symbols wrapping a placeholder. In this case, one set of greater than and less than symbols is required in the actual value and should not be replaced. For example, From: "Example" <<example@example.com>> will become From: "Example" <example@example.com>.

Once you have your terminal open and have saved your API key, you must Base64 encode the API key. Note that it is not secure to put your API key into an external webpage for a conversion, so we recommend using a conversion in your terminal. If you are on Mac or Linux, you can use the pre-installed OpenSSL package to Base64 encode a string with the following command.

echo -n '<YOUR_API_KEY>' | openssl base64

Save your encoded key for a later. Also, be sure you have not included any newline or whitespace characters by accident. This can happen when copying the encoded key from a shell that line wraps output. SMTP is a line-oriented protocol, and linefeed characters will prevent you from authenticating successfully.

Telnet does not register backspaces correctly, so you must type your commands correctly or copy and paste them from this page.

You may need to install Telnet on your machine. Telnet comes natively on some operating systems; However, recent releases of MacOS no longer include Telnet, and Telnet must be enabled manually on Windows 10 and Windows 11.

You can install Telnet on MacOS using Homebrew.

To enable Telnet on Windows, navigate to Windows Features > Turn Windows Features on or off from the Windows Control Panel. Check the box next to Telnet Client, and select OK.

  1. Start a Telnet session by typing the following in the terminal:
TELNET smtp.sendgrid.net 25

SendGrid accepts unencrypted and TLS connections on ports 25, 587, & 2525. You can also connect via SSL on port 465. Many hosting providers and ISPs block port 25 as a default practice. If your Telent session continually times out or will not connect using port 25, it is likely that your ISP or hosting provider is blocking the port. You can contact your host/ISP to find out which ports are open for outgoing SMTP relay. We recommend using port 587 to avoid any rate limiting that your server host may apply.

  1. Once you successfully connect to SendGrid, log in to the server by typing the following:
AUTH LOGIN

The mail server will respond with 334 VXNlcm5hbWU6, which is a Base64 encoded request for your username.

  1. Input YXBpa2V5 and press Enter on your keyboard. Twilio SendGrid requires you to authenticate using an API key. When using Basic Authentication and an API key, you must use the string apikey in place of your account username. The string apikey is YXBpa2V5 when Base64 encoded, which is why we use it in this step.

The mail server will respond with 334 UGFzc3dvcmQ6. This response is a Base64 encoded request for your password (your API Key).

  1. Enter your Base64 converted API key in the next line as the password and press Enter.

The mail server will respond with 235 Authentication successful. Getting this far indicates that your connection to smtp.sendgrid.net over the chosen port is open and that your API key is valid.

  1. Next, add the email that you’re sending from using the SMTP MAIL FROM command and press Enter.
MAIL FROM: <SENDER_EMAIL>

The mail server will respond with 250 Sender address accepted.

  1. Add the email that you’re sending to use the SMTP RCPT TO command and press Enter.
RCPT TO: <RECIPIENT_ADDRESS>

Note that you can add more RCPT TO addresses during this step. Repeat the process by adding another RCPT TO command and pressing Enter for each recipient you intend to deliver the message to.

The mail server will respond with 250 Recipient address accepted after each recipient is added.

  1. On the next line, type DATA and press Enter.

The mail server will respond with 354 Continue. Unlike the MAIL FROM and RCPT TO commands, which are part of the email envelope, the DATA command is not meant to contain information that routes your email from a sender to a recipient. Instead, DATA allows you to modify the content of your message.

  1. Optionally, add a mail-to header to add the name and email address of the recipient to the email header and press Enter. Note that the name should be wrapped in quotation marks, and the address should be wrapped in a greater than and less than symbol.
To: "<RecipientName>" <<RecipientEmailAddress>>
  1. Next, add a from header to add the name and email address of the sender to the email header and press Enter. If a from header is not included, SendGrid will block your email because it doesn’t follow RFC 5322 compliance guidelines. Note that the name should be wrapped in quotation marks, and the address should be wrapped in a greater than and less than symbol.
From: "<SenderName>" <<SenderEmail>>
  1. Include a subject line and press Enter.
Subject: <EMAIL_SUBJECT>
  1. Press Enter again to add a carriage line return. Then add the body content of the message and press Enter.
"<MESSAGE>"

For example:

“This is a test for the SMTP relay."
  1. Finally, send the email by typing a period, ., and then pressing Enter.

The mail server will return 250 Ok: queued as <examplestring1234>. This means the email has been queued to send. The queue moves very quickly, and you should see mail delivered to the designated recipients shortly.

  1. Exit the Telnet connection by typing quit and pressing Enter.

The full command should look like the following example.

235 Authentication successful
MAIL FROM:tiramisu@example.com
250 Sender address accepted
RCPT TO:person1@sendgrid.com
250 Recipient address accepted
DATA
354 Continue
From: "Tira Misu" <tiramisu@example.com>
To: "Person 1" <person1@sendgrid.com>
Subject: Test message subject

"This is the test message body."
.
250 Ok: queued as Yo60h6C5ScGPeP5fUWU3K

Now that you've sent a test email, learn to integrate your servers with our SMTP service.

Message size limit: The total message size should not exceed 20MB. This includes the message itself, headers, and the combined size of any attachments.

Rate this page:

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif