How to send an Email with SMTP

The Simple Mail Transfer Protocol (SMTP) provides the language that transmits email from one server to another. Twilio SendGrid provides an SMTP service to deliver your email using its servers.

To set custom email handling instructions, use a JSON-encoded list called the X-SMTPAPI header in the Twilio SendGrid SMTP API. To modify your message in the ways you specify, Twilio SendGrid parses the X-SMTPAPI header.

To learn more about SMTP, see the SMTP Service Crash Course in the Twilio blog.

Before you start this tutorial, complete the following prerequisites.

1. Install OpenSSL.

   • OpenSSL comes installed on macOS and Linux.
   • If you use Windows, download and run the official installer.

2. Install telnet. See the PuTTY for Windows, macOS Homebrew formula, or Linux instructions.

3. Sign up for a SendGrid account

4. Create and store a SendGrid API key with full access "Mail Send" permissions.

5. Open your terminal, command prompt, or command line.

6. Encode your API key using Base64, use the following command.

   Copy code block

   echo -n '<YOUR_API_KEY>' | openssl base64

   Never convert your API key using an external webpage, always convert it in your terminal with OpenSSL.

7. Save your encoded key for later.
   Check that the API key doesn't include any newline or whitespace characters by accident. This can happen when copying the encoded key from a shell that line wraps output. SMTP uses line breaks to end commands, so Linefeed characters prevent successful authentication.

8. Verify your Sender Identity.

To see how the SMTP server requests and responds, use Telnet.

1. Type the following in the terminal and start a Telnet session:

   Copy code block

   telnet smtp.sendgrid.net 587

   Use port 587. This should avoid rate limiting or connection blocking from ISPs and hosting providers.

2. After connecting to Twilio SendGrid, log in to the mail service using the following SMTP command:

   Copy code block

   AUTH LOGIN

   The mail server responds with 334 VXNlcm5hbWU6, a Base64-encoded request for your username.

3. Type YXBpa2V5 and press Enter on your keyboard.
   Twilio SendGrid authenticates using an API key, so it expects apikey instead of your account username. When Base64-encoded, apikey becomes YXBpa2V5.

   The mail server responds with 334 UGFzc3dvcmQ6, a Base64-encoded request for your API Key as a password.

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

   The mail server responds with 235 Authentication successful. This indicates an open connection to smtp.sendgrid.net on port 587 and that you have a valid API key.

5. Add the email that you're sending from using the SMTP MAIL FROM command and press Enter.

   Copy code block

   MAIL FROM: <SENDER_EMAIL>

   The mail server responds with 250 Sender address accepted.

6. Type the SMTP RCPT TO command, then the recipient email address, and press Enter.

   Copy code block

   RCPT TO: <RECIPIENT_ADDRESS>

   To add more recipient addresses, type RCPT TO <RECIPIENT_ADDRESS> and press Enter for each recipient.

   After each recipient, the mail server should respond with 250 Recipient address accepted.

7. Type DATA and press Enter.

   The mail server responds with 354 Continue. Unlike the MAIL FROM and RCPT TO commands, which define the email envelope and route your message to the recipient, the DATA command modifies the content of your message.

8. You can add a mail-to header to add the name and email address of the recipient to the email header and press Enter.
   Note: Wrap the name in quotation marks (") and the address in angle brackets (<,>).

   Copy code block

   To: "<RecipientName>" <<RecipientEmailAddress>>

9. Add a From header to add the name and email address of the sender to the email header and press Enter.

   (warning)

   SMTP requires a From header

   If you omit a From header, Twilio SendGrid blocks your email as it violates RFC 5322.

   Copy code block

   From: "<SenderName>" <<SenderEmail>>

10. Add a Subject line and press Enter.

    Copy code block

    Subject: <EMAIL_SUBJECT>

11. Press Enter to start the body of your message.

12. Type the body content then press Enter.

    Copy code block

    "<MESSAGE>"

    For example:

    Copy code block

    "This is a test for the SMTP relay."

13. Type a period (.) as the signal to end the email body, then press Enter. This sends the email.

    The mail server returns 250 Ok: queued as <examplestring1234>. The mail server has put this email into the send queue. This queue clears quickly. The mail should deliver to the designated recipients in a short time.

14. To exit the Telnet connection, type quit and press Enter.

The following example shows the all user inputs and SMTP server responses.

1
235 Authentication successful
2
MAIL FROM:[email protected]
3
250 Sender address accepted
4
RCPT TO:[email protected]
5
250 Recipient address accepted
6
DATA
7
354 Continue
8
From: "Tira Misu" <[email protected]m>
9
To: "Person 1" <[email protected]m>
10
Subject: Test message subject
11

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

• Getting Started with the UI
• Getting Started with the API
• SMTP Service Crash Course
• Integrating with the SMTP API
• Building an SMTP Email