SMTP Specification
Simple Mail Transfer Protocol (SMTP) is a communication protocol that enables the safe and reliable exchange of email messages from one user to another. Infobip provides an SMTP server for the secure delivery of emails.
The Infobip SMTP API behaves in the same way as any SMTP-compliant server, for example, your ISP, Gmail, or your corporate email server. This means that you can configure any email provider, such as Outlook or Thunderbird, to use Infobip SMTP as a relay. There is, however, a restriction when it comes to senders, which can be used for relying upon the messages.
You should also use your Infobip-supplied credentials for authentication.
Integrate with SMTP API
To integrate with the Infobip SMTP API, use the following settings to set up a basic client configuration. Use the relevant settings for your region.
Port 587 is recommended and supports STARTTLS and SSL.
You can also use port 465 (recommended if you can not use 587 for any reason) and 25 (although it is not recommend generally because some ISPs tend to block this port).
For authorization to any SMTP, use Infobip Account Basic Authorization (username and password).
Region |
Server Name |
Port |
---|---|---|
Frankfurt (FR) |
smtp-api.infobip.com |
587, 465, 25 |
EU | smtp-api-eu.infobip.com | 587, 465, 25 |
USA * | smtp-api-ny.infobip.com | 587 only |
India (Mumbai) | smtp-api-mum.infobip.com | 587, 465, 25 |
Indonesia | smtp-api-id.infobip.com | 587 only |
MENA | smtp-api-ae2.infobip.com | 587 only |
* USA: For the email message to be processed and sent within the specified region (Domain Controller), the IP address from that region must be used on a domain you are using. To enable the IP address, contact [email protected] or your dedicated CSM.
Authentication
SMTP authentication provides basic security to ensure that messages are safely exchanged and prevent misuse of the server.
Infobip SMTP supports the PLAIN and LOGIN authentication mechanisms. Both mechanisms require a username and password. For basic authentication, use your Infobip account username and password.
- PLAIN: transmits the username and password in one string encoded in Base64
- LOGIN: works in the same way as PLAIN but transmits the username and password individually
For authentication with an Infobip API key, use the following credentials:
Settings | Value |
---|---|
User Name | App |
Password | API key (same as for authentication over HTTP) |
See API Authentication for more information on using API Keys.
Optional headers
Custom headers let you provide additional information for your outgoing SMTP emails.
Here's a list of supported headers.
Property name |
Header name |
Description |
---|---|---|
bulkId |
X-IB-bulk-id |
The ID uniquely identifies the sent email request. |
trackingUrl |
X-IB-tracking-url |
The URL on your callback server on which the open and click notifications will be sent. |
intermediateReport |
X-IB-intermediate-report |
Set to true for receiving the real-time Intermediate delivery report on your callback server. |
notifyUrl |
X-IB-notify-url |
The URL on your callback server on which the Delivery report will be sent. |
notifyContentType |
X-IB-notify-content-type |
Preferred Delivery report content type. Can be application/json or application/xml. |
callbackData |
X-IB-callback-data |
Additional client's data that will be sent on the notifyUrl. |
Supported SMTP Commands
The Infobip SMTP server supports the following commands:
SMTP command |
Description |
---|---|
HELP | Returns information about the full list of SMTP commands. |
HELO | Starts the conversation identifying the sender server and is generally followed by its domain name. |
EHLO | Starts the conversation identifying the sender server when the server is using the Extended SMTP protocol. |
AUTH | Client authenticates itself to the server using the username and password. |
MAIL FROM | Sender states the source email address in the “From” field and starts the email transfer. |
RCPT TO | Identifies the recipient of the email. For multiple recipients, the command is repeated for each address. |
DATA | Email content begins to be transferred; it’s generally followed by a 354 reply code given by the server, giving the permission to start the actual transmission. |
RSET | Terminates the email transmission but does not close the SMTP conversation. |
QUIT | Terminates and closes the SMTP conversation. |
NOOP | Checks whether the server can respond. |
STARTTLS |
Starts the secure connection. |
NOTE
Email addresses present in the DATA (to and cc) should also be present in the RCPT TO field.
Test SMTP with Telnet
The following instructions explain how to test your SMTP communication with Telnet, describing:
- Starting SMTP communication
- How to authenticate
- Adding email content
Starting SMTP communication
To start using SMTP communication, try connecting to the Infobip SMTP API. Infobip accepts STARTTLS connections on port 587. In addition, ports 25 and 465 are supported on-demand.
To use these instructions, you need to have installed openssl on your machine.
- Open the Command Prompt or PowerShell and install openssl to connect using STARTTLS. Type:
openssl s_client -crlf -connect smtp-api.infobip.com:587 -starttls smtp
The -crlf option forces a line break when you press Enter, which is required by some servers.
You will see a response something like the following:
CONNECTED(00000220) --------------you will see the whole certificate value here------------------ 250 Ok
- Introduce your server to the Infobip SMTP server, using the EHLO command:
EHLO smtp-api.infobip.com
Use this command to check the server status. The server will respond with the EHLO options that are supported.
The Infobip supported options are:
250-smtp.email-messaging.com 250-8BITMIME 250-SIZE 20971520 250-STARTTLS 250-AUTH LOGIN PLAIN 250 Ok
- Infobip servers require you to authenticate using your Infobip account username and password. Type:
AUTH LOGIN
The mail server will respond with 334 VXNlcm5hbWU6
, which is a Base64 encoded request for your username, so you need to provide your Base64 converted username.
- Type Base64 converted username
The mail server will respond with 334 UGFzc3dvcmQ6
. This response is a Base64 encoded request for your password, so you need to respond with the Base64 converted password.
- Type Base64 converted password
The mail server will respond with 235 Authentication successful.
When you have completed these steps, your connection to smtp-api.infobip.com over the chosen port is open and your username and password are valid.
- Add the email that you are sending from using the SMTP MAIL FROM command and press Enter.
MAIL FROM:
The mail server will respond with 250 Sender address accepted.
- Add the email that you are sending to using the SMTP RCPT TO command and press Enter.
RCPT TO:
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.
- 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.
- Optionally, add a mail-to header to add the name to 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: "
- In a similar way, you can also define name for a sender email address which you will use for testing.
From: "
- Include a subject line in your email and press Enter.
Subject:
- Press Enter again to add a carriage line return. Then add the body content of the message and press Enter.
"
For example:
“The body of the mail goes here."
- Finally, send the email by typing a period ( . ) and pressing Enter. The period is to signify that the mail body is now completed.
The mail server will return 250 Ok. 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.
To exit the Telnet connection, type quit and press Enter.
Testing SMTP with Thunderbird
The following instructions explain how to test your SMTP communication with ThunderBird.
1. Install Thunderbird.
2. Configure one of your existing (incoming) email addresses. You have to configure the client email address before you can send an email.
3. Right-click on your email account > Settings > Outgoing Server and then click Add.
4. Add a description, for example infobip smtp api, and set the following properties.
Property |
Value |
---|---|
Server Name |
smtp-api.infobip.com |
Port |
587 |
Connection security |
STARTTLS |
Authentication method |
Normal Password |
User Name |
username |
5. Replace the username with the correct account authentication data. Make sure you set this server as default.
6. Compose your email. The senders are restricted on the Infobip platform, so you must use one of your Infobip verified domains (or registered senders). In Thunderbird, click Customize From Address from the From field.
7. Click Send. You may be asked to provide a password in this step.
NOTE
If your credentials are not correct, or if the sender is not authorized, you will get an error message.