Send email over SMTP

SMTP (Simple Mail Transfer Protocol) is a widely used and reliable standard communication protocol for email transmission across the internet. The Infobip SMTP API builds on top of SMTP by providing a secure and scalable interface for sending emails.

This section provides a comprehensive guide on how to integrate with the SMTP API and to send emails over SMTP.

SMTP API integration

To integrate with the SMTP API, you need the applicable SMTP server information. The following table shows the available endpoints for the SMTP servers and port numbers, dependent on each region.

For Schrems II (opens in a new tab) compliance, use smtp-api-eu.infobip.com with one of the standard available ports: 587 or 465.

When using port 587, an explicit STARTTLS command is required, while a connection over port 465 implies that the TLS handshake has already been completed. TLS communication is mandatory on any port.

SMTP authentication

SMTP authentication (SMTP AUTH) ensures that only authorized users can send emails through the Infobip SMTP API. By enforcing valid credentials before permitting message transmission, SMTP AUTH helps prevent unauthorized access or server abuse.

Infobip SMTP supports the PLAIN and LOGIN authentication mechanisms:

• PLAIN - transmits the username and password in a single Base64-encoded string
• LOGIN - transmits the username and password individually, each encoded as Base64 string

Your authentication credentials can be submitted in two ways:

1. Basic authentication - use your Infobip account username and password.
2. API key authentication - username is always App, and the password is the API key created on your Infobip account.

In both cases, the username and password must be submitted as Base64-encoded strings.

See API authentication for more information on using API keys.

Supported SMTP commands

The Infobip SMTP server supports the following commands:

Optional custom headers

Custom headers allow you to include additional information in outgoing SMTP emails. The following table provides a list of custom header names used in email communication.

Set up an integration with Infobip SMTP API

This is the process for integrating with the Infobip SMTP API:

1. Open a secure connection - Establish a secure connection to the Infobip SMTP server.
2. Initiate a new SMTP session - Start a new session to begin the process of sending an email.
3. Authenticate your SMTP connection - Provide your credentials to authenticate the connection and gain access to the SMTP server.
4. Define an envelope - Specify the sender and recipient email addresses to set up the email envelope.
5. Send the message content - Transmit the email content through the SMTP server to deliver the message to the recipient.

The following sections describe the steps in detail.

Open a secure connection

Start a new SMTP connection to smtp-api.infobip.com using openssl. Connect to port 587 and request a secure communication by typing the following in a command prompt:

openssl s_client -connect smtp-api.infobip.com:587 -starttls smtp -quiet

Use the -quiet option to keep the connection open even when special characters are used as input. For example, the Q letter closes the connection without this option.

If you experience issues with this command, try using the -crlf option. This forces a line break when you press Enter, and may be required by some servers.

For example:

openssl s_client -crlf -connect smtp-api.infobip.com:587 -starttls smtp -quiet

The server returns the response containing information about the certificate and ending with 250 OK.

Initiate a new SMTP session

Initiate an ESMTP session by introducing your client to the Infobip SMTP server using the EHLO command, which also prompts the server to return a list of supported SMTP extensions:

EHLO <client_hostname>

The Infobip SMTP server responds with a list of supported SMTP extensions, ending with 250 OK. For example:

250-smtp.email-messaging.com
250-8BITMIME
250-SIZE 20971520
250-STARTTLS
250-AUTH LOGIN PLAIN
250-ENHANCEDSTATUSCODES
250-PIPELINING
250 OK

Authenticate your SMTP session

To ensure that only authorized users can send emails through the Infobip SMTP API, you need to use SMTP authentication:

1. Begin the authentication process by using the LOGIN authentication mechanism.
2. Then, send the AUTH LOGIN command to the SMTP server.
3. The server will then prompt you to enter your username and password in sequence, and respond with a confirmation once authentication is successful.

Note the following:

• The SMTP server responds with 334 VXNlcm5hbWU6, which is a Base64-encoded prompt for your username. Enter your username encoded in Base64.
• The SMTP server responds with 334 UGFzc3dvcmQ6, which is a Base64-encoded prompt for your password. Enter your password encoded in Base64.

If the username and password credentials are valid, the Infobip SMTP server responds with 235 2.7.0 Authentication successful.

Define an envelope

After you complete authentication, define an envelope by specifying the sender's and recipient's addresses:

1. To specify the sender address, use the MAIL command: MAIL FROM: <sender_address>
2. You can optionally include the SIZE parameter in the MAIL command to declare the message size in bytes: MAIL FROM: <sender_address> SIZE=number_of_bytes
3. When you use the SIZE parameter, the server immediately checks if it can process the message. If the message size exceeds the maximum allowed limit, the server responds that the message is too large. If you do not include the SIZE parameter, this check occurs later with the actual message content during the DATA command.
4. Once the sender is accepted, the Infobip SMTP server responds with 250 2.1.0 Sender <sender_address> OK.
5. To specify the recipient, use the RCPT command: RCPT TO: <recipient_address>
6. For multiple recipients, repeat the RCPT command for each one.
7. When the recipient is accepted, the Infobip SMTP server responds with 250 2.1.5 Recipient <recipient_address> OK.
8. After you successfully send the envelope addresses, proceed to announce that you want to send the message content using the DATA command.

Command pipelining

The Infobip SMTP server supports command pipelining.

When using SMTP commands without pipelining, the interaction between the client and the server follows a request–response cycle. The client must wait for the server's response after each command before sending the next one.

Pipelining allows the client to send the MAIL, RCPT, and DATA commands simultaneously, without waiting for the server's response to each command. This approach significantly reduces the number of round trips and latency per transaction. The server provides clear and descriptive responses for each command or address sent.

The following examples show the command order and server responses for without pipelining and with pipelining.

Send the message content

You can request to send the message content by sending the DATA command. If everything is in order with the previously sent envelope addresses, the server responds with:

354 End data with <CR><LF>.<CR><LF>

After receiving the response with status code 354 from the server, you can send the MIME content of the message.

The following is the simplest example of an acceptable raw email MIME message:

From: "Sender Name" <sender@example.com>
To: recipient@example.com
Subject: Simple subject
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="example_boundary"
 
--example_boundary
Content-Type: text/plain; charset="utf-8"
 
This is the plain text content.
--example_boundary--

This is the fully featured MIME example:

Subject: Fully Featured SMTP Example
From: "Sender Name" <sender@example.com>
Reply-To: reply-to@example.com
To: recipient_1@example.com, recipient_2@example.com
Cc: recipient_cc@example.com
Message-ID: <custom-message-id@example.com>
X-IB-Bulk-Id: 1234567890
X-IB-Tracking-Url: https://www.example.com/email/webhook/server
X-IB-Intermediate-Report: true
X-IB-Notify-Url: https://www.example.com/email/delivery/server
X-IB-Notify-Content-Type: application/json
X-IB-Callback-Data: [{"id": 1, "desc": "Callback Data Example as JSON"}]
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="example_boundary"
 
--example_boundary
Content-Type: text/html; charset=UTF-8
 
<html>
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <p>Hello world from Infobip! Happy testing :)</p>
    <img src="cid:pixel_cid" alt="Pixel as the inline image">
  </body>
</html>
--example_boundary
Content-Type: image/png
Content-Id: <pixel_cid>
Content-Disposition: inline; filename="pixel.png"
Content-Transfer-Encoding: base64
 
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mPkT1GpBwACOQEYP+FHpAAAAABJRU5ErkJggg==
--example_boundary
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="simple.pdf"
Content-Transfer-Encoding: base64
 
JVBERi0xLjEKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHMgWzMgMCBSXS9Db3VudCAxPj5lbmRvYmoKMyAwIG9iajw8L1R5cGUvUGFnZS9QYXJlbnQgMiAwIFIvTWVkaWFCb3hbMCAwIDMwMCAyMF0vQ29udGVudHMgNCAwIFIvUmVzb3VyY2VzPDwvRm9udDw8L0YwIDUgMCBSPj4+Pj4+ZW5kb2JqCjQgMCBvYmo8PC9MZW5ndGggNjM+PnN0cmVhbQpCBiAwIFRMIDAgMCAxMCAxMCAwIDAKL0YwIDEyIFRmCjI1IDAgVGQKKCJTaW1wbGUgUERGIC0gRnVsbHkgRmVhdHVyZWQgU01UUCIpIFRqCkUKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvTmFtZS9GMC9CYXNlRm9udC9IZWx2ZXRpY2EvRW5jb2RpbmcvV2luQW5zaUVuY29kaW5nPj5lbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMTAwIDAwMDAwIG4gCjAwMDAwMDA2MDggMDAwMDAgbiAKMDAwMDAwMTcyOSAwMDAwMCBuIAowMDAwMDAxOTMxIDAwMDAwIG4gCnRyYWlsZXI8PC9Sb290IDEgMCBSL1NpemUgNj4+CnN0YXJ0eHJlZgoyMDQxCiUlRU9GCg==
--example_boundary--

You can signal the end of the message by sending <CRLF>.<CRLF> after the MIME content. If the message is accepted, the Infobip SMTP API responds with 250 2.6.0 Message queued as <message_id>.

Send the QUIT command to terminate the SMTP session and close the connection.