Development

How To Use HTTP API For Sending Emails

Introduce email sending and tracking without additional coding.

March 27 2017

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. According to Ericsson, by 2020 70% of world’s population will be using smartphones and 90% will be covered by mobile broadband networks. Also, it is important to notice that more than 50% of emails are open on a mobile device, rather than desktop, and the numbers keep on growing. This means that users will be able to access their email accounts at any time.

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 e-mails.

Think ahead about your domain, because the e-mail 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: support@infobip.com.

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:


curl -s --user user:password \
https://api.infobip.com/email/1/send \
-F from='company@somecompany.com' \
-F to='john.smith@somedomain.com' \
-F subject='Mail subject text' \
-F text='Mail body text'

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:

curl -s --user user:password \
https://api.infobip.com/email/1/send \
-F from='Jane Smith ' \
-F to='john.smith@somedomain.com' \
-F to='tom.smith@somedomain.com' \
-F subject='Mail subject text' \
-F text='Mail body text' \
--form-string html='<h1>Html body</h1><p>Rich HTML message body.</p>' \
-F attachment=@files/image1.jpg

With a response:

{
 "messages": [
   {
     "to": "john.smith@somecompany.com",
     "messageCount": 1,
     "messageId": "9129e972-be85-49ed-b0e9-f51fbd2b27c0",
     "status": {
       "groupId": 1,
       "groupName": "PENDING",
       "id": 7,
       "name": "PENDING_ENROUTE",
       "description": "Message sent to next instance"
     }
   },
   {
     "to": "tom.smith@somecompany.com",
     "messageCount": 1,
     "messageId": "cd0c5682-42e2-481a-be95-15ed72450646",
     "status": {
       "groupId": 1,
       "groupName": "PENDING",
       "id": 7,
       "name": "PENDING_ENROUTE",
       "description": "Message sent to next instance"
     }
   }
 ]
}

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


GET /email/1/reports HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json

Result:

{
 "results": [
   {
     "messageId": "bbcc6960-1fcb-497c-b7ea-83ccba41492e",
     "to": "recipient@infobip.com",
     "sentAt": "2016-08-31T13:25:18.477+0000",
     "doneAt": "2016-08-31T13:25:50.893+0000",
     "messageCount": 1,
     "price": {
       "pricePerMessage": 0,
       "currency": "UNKNOWN"
     },
     "status": {
       "groupId": 3,
       "groupName": "DELIVERED",
       "id": 5,
       "name": "DELIVERED_TO_HANDSET",
       "description": "Message delivered to handset"
     },
     "error": {
       "groupId": 0,
       "groupName": "OK",
       "id": 0,
       "name": "NO_ERROR",
       "description": "No Error",
       "permanent": false
     },
     "channel": "EMAIL"
   }
 ]
}

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:

GET /email/1/reports?messageId=bbcc6960-1fcb-497c-b7ea-83ccba41492e HTTP/1.1

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

GET /email/1/reports?limit=2 HTTP/1.1

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:

{
 "results": [
   {
     "messageId": "64c98929-f160-4e2c-b156-ca88cc733547",
     "to": "recipient@infobip.com",
     "from": "sender@infobip.com",
     "text": "Test text",
     "sentAt": "2016-09-01T10:29:00.440+0000",
     "doneAt": "2016-09-01T10:29:01.130+0000",
     "price": {
       "pricePerMessage": 0.0005,
       "currency": "EUR"
     },
     "status": {
       "groupId": 3,
       "groupName": "DELIVERED",
       "id": 5,
       "name": "DELIVERED_TO_HANDSET",
       "description": "Message delivered to handset"
     },
     "channel": "EMAIL"
   }
 ]
}

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:

GET /email/1/logs?messageId=64c98929-f160-4e2c-b156-ca88cc733547,60d586a1-6448-4c5f-860d-be3ddbea16da HTTP/1.1

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


GET /email/1/logs?sentSince=2016-08-22T17:42:05.390%2b01:00&generalStatus=DELIVERED HTTP/1.1

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.

Start sending emails today

Learn more