How to use HTTP API for sending emails

Communication technologies have advanced to the point where it’s not enough to use one or two channels. Fact is, each channel has its own benefits and drawbacks. You might use push to target and reach users at a specific location. SMS gets read. Viber is interactive and fun. Email respects the client’s timetable.

In any case, today’s consumer-centric ecosystem demands that you adapt your communications strategies to the needs of the client. Most of them already have a platform of choice. They are already using Gmail, Facebook Messenger or Viber and Outlook, plus a number of apps. The key thing is that they are using each of these channels for a specific purpose.

For example, some might use Messenger to converse in real time, while at the same time receiving newsletters from their favorite brands via Gmail. Some prefer to be contacted over SMS, since it’s still the most reliable communications channel out there. Others prefer to receive voice calls for important alerts. Point is, your client base is diverse in choosing the ways it wants to be reached.

Why Email?

Because of its unique nature, email is an essential part of omnichannel communications. It’s one of the most cost effective and least intrusive channels, which makes it frequent user choice when engaging with a brand. We mentioned newsletters, but there are a number of cases where email works – from account verification emails to password resets and account recoveries.

This is why email generates billions and billions of messages per day with users accessing their email accounts at all times, and over multiple devices.

Our HTTP API offers sending simple and fully featured emails; you will be able to send HTML emails with attachments and view delivery reports and email logs. However, before you start sending emails you have to get a valid Infobip account.

How to create an account

In case you’ve been using our other API services, you already have a valid Infobip account, and you can use that same account for sending emails.

Think ahead about your domain, because the email sender reputation is tied to your domain name, as well as the IP address. The problem comes when there’s a possibility that you become a ‘bad’ sender, which can highly affect your domain. Once you become a bad sender, you will have difficulties with regaining trust, so keep in mind that separating domains for the type of messages you are sending is a good idea.

If you’re not sure right away about your domain plan – don’t worry. You can use our test domain to try out the service and start using your own domain later on. But, after you’ve chosen your preferred domain, you can contact your account manager, so we could integrate it within our platform. After receiving additional instructions about DNS configuration and how to establish a proper communication channel between your domain and your platform, you will be able to start following the next steps and successfully send an email.

For any additional questions feel free to write to us at: [email protected].

Let’s send an email

After setting up the account you are ready to start sending emails. You can send a simple email message or a fully featured one. If you decide to send a simple email, it means you will be sending a single email message to only one destination address with a request:

		
	

On the other hand, you can send a fully-featured email that represents a message with attachment(s) that can be sent to one or more destination addresses:

		
	

With a response:

		
	

This is the example of an email with one attachment, that is sent to two destination addresses. If you want to send an email with more than one attachment, just add multiple attachment parameters in the request.

The fully featured email also supports adding one or more recipients to CC & BCC. However, if you are going to add recipients to CC or BCC, at least one TO recipient is mandatory.

		
	

The response header HTTP status code for each successful request will be 200 OK and if you try to send a message without authorization, you will receive an error 401 Unauthorized.

Email delivery reports and logs

Email delivery reports

After you’ve sent an email, you can get a one-time delivery report. Delivery reports will confirm that the email you’ve sent was successfully delivered. They can only be retrieved one time, so once you retrieve a delivery report, you won’t be able to get the same report again.

You can use parameters for receiving delivery reports, but you can also make a request without any query parameters:

		
	

Result:

		
	

A delivery report without any parameters will give you detailed information about your sent emails, including email status, message ID, time and date of sending/receiving emails, information about occurred errors, etc.

Additionally, you can get delivery reports using messageId:

		
	

And, the other possibility is to initial two delivery reports:

		
	

Both of the requests provide message details like a query without parameters, but the difference is that the messageID request retrieves information about that exact message, and two delivery reports information about two initial messages.

Email logs

Just like delivery reports, email logs can give you additional information about your sent messages. The main difference is that logs are available for the last 48h, they can be requested as many times as you want, and you can see the result for your messages regardless their current status:

Result:

		
	

The response contains information about all of the emails that were sent through Infobip platform for the past 48h. None of the queries are mandatory for this kind of request, but if you need to find a precise message you can use parameters for filtering.

For instance, logs can be retrieved by only one or, in this case, multiple message IDs:

		
	

Also, combining parameters will help you in filtering your messages even more precisely:

		
	

This request has two filters (parameters) – sentSince and generalStatus, which would be identified as a single parameter, and the response would contain the message log with all of the emails sent and delivered since the date in the request.

The status code would be the same as it was for sent messages; the response header HTTP status code will be 200 OK if successful and the message logs or delivery report will be returned, but if you try to send the message without authorization, you will get a response with HTTP status code 401 Unauthorized.

This post should help you with the integration of HTTP API, and if there’s a need for any additional help visit our developer site.

Mar 27th, 2017
7 min read