# 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`.

Important
It is strongly recommended that clients **reuse SMTP connections** as much as possible. Sending multiple emails over a single SMTP connection improves efficiency and optimizes resource utilization.

---

## 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:

```mime copy filename="Supported SMTP extensions"
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.

Note
The maximum number of recipients per SMTP transaction is limited to 1000 recipients.

---

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

| Without pipelining | With pipelining |
| --- | --- |
| {`Client → MAIL FROM:Server → 250 2.1.0 Sender0K

Client → RCPT TO:Server → 250 2.1.5 Recipient0K

Client → RCPT TO:Server → 550 5.7.1 Recipientnot allowed

Client → RCPT TO:Server → 501 5.1.7 Bad recipient address ‹invalid_address›

Client → DATA

Server → 354 End data with.`} | {`Client → MAIL FROM:Client → RCPT TO:Client → RCPT TO:Client → RCPT TO:Client → DATA

Server → 250 2.1.0 Sender0K

Server → 250 2.1.5 Recipient0K

Server → 550 5.7.1 Recipientnot allowed

Server → 501 5.1.7 Bad recipient addressServer → 354 End data with.`} |

Important
Do not pipeline the new SMTP command immediately after the `<crlf>.<crlf>` sequence. Instead, wait for the server’s response confirming the end of the email content before either ending the session or beginning a new message transaction.

---

## 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:

```mime copy filename="Raw MIME message example"
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:

```mime copy filename="Fully-featured MIME message 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
 
Hello world from Infobip Happy testing :)
 
--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+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHMgWzMgMCBSXS9Db3VudCAxPj5lbmRvYmoKMyAwIG9iajw8PC9UeXBlL1BhZ2UvUGFyZW50IDIgMCBSL01lZGJveFswIDAgMzAwIDIwXS9Db250ZW50cyA0IDAgUj9SZXNvdXJjZXM8PC9Gb250Dw8L0YwIDUgMCBSPj4+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.

Note
The `<message_id>` is a unique identifier assigned by the Infobip SMTP API to each accepted message. When retrieving delivery reports, you can use the `<message_id>` to identify which report belongs to which original message. Infobip SMTP API does the relaxed alignment check (root domain matching) between the `Envelope From` and `Header From` domains.