NAV Navbar
cURL Ruby Python PHP

EMAIL API

This API allows you to automatize both single and bulk email message requests and the recovery of sent status through its endpoints. It uses HTTP protocol with TLS POST requests with JSON parameters.

User authentication

In order to successfully use our API, you are required to present a valid user name - or email - and the associated authentication token. While creating the request, you have to provide the following parameters on the headers:

Field Details Data Type
UserName Your username or email String
AuthenticationToken Your authentication token. Get yours here String

Connection Details

Hostname api-messaging.movile.com
APIs SendEmail /v1/email/send
SearchEmail /v1/email/status/search
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authentication username + token
Portal messaging.movile.com

SendEmail

SendEmail request


curl --request POST \
  --url https://api-messaging.movile.com/v1/email/send \
  --header 'authenticationtoken: <authenticationtoken>' \
  --header 'content-type: application/json' \
  --header 'username: <username>' \
  --data '{
    "fromEmail": "notification@movile.com",
    "fromName": "Notifications",
    "replyTo": "replyTo@movile.com",
    "subject": "Marketing e-mail",
    "campaignAlias": "MyCampaign",
    "recipients": [{
            "correlationId": "1234",
            "emailAddress": "recipient-1@movile.com",
            "emailName": "Recipient-1",
            "extraInfo": "Extra e-mail info1",
            "substitutionData": {
                "name": "Recipient-1"
            }
        },
        {
            "correlationId": "567",
            "emailAddress": "recipient-2@movile.com",
            "emailName": "Recipient-2",
            "extraInfo": "Extra e-mail info2"
        }
    ],
    "emailHtml": "<html> Hi, {{name}}, this is the email HTML body </html>",
    "emailText": "Email text body",
    "substitutionData": {
        "name": "Recipient-1"
    },
    "attachments": [{
        "data": "Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh",
        "name": "billing.pdf",
        "type": "application/pdf"
    }]
}'

require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/email/send")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["username"] = '<username>'
request["authenticationtoken"] = '<authenticationtoken>'
request["content-type"] = 'application/json'
request.body = "{\n    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}"

response = http.request(request)
puts response.read_body
import requests

url = "https://api-messaging.movile.com/v1/email/send"

payload = "{\n    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}"
headers = {
    'username': "<username>",
    'authenticationtoken': "<authenticationtoken>",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/email/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n    \"fromEmail\": \"notification@movile.com\",\n    \"fromName\": \"Notifications\",\n    \"replyTo\": \"replyTo@movile.com\",\n    \"subject\": \"Marketing e-mail\",\n    \"campaignAlias\": \"MyCampaign\",\n    \"recipients\": [{\n            \"correlationId\": \"1234\",\n            \"emailAddress\": \"recipient-1@movile.com\",\n            \"emailName\": \"Recipient-1\",\n            \"extraInfo\": \"Extra e-mail info1\",\n            \"substitutionData\": {\n                \"name\": \"Recipient-1\"\n            }\n        },\n        {\n            \"correlationId\": \"567\",\n            \"emailAddress\": \"recipient-2@movile.com\",\n            \"emailName\": \"Recipient-2\",\n            \"extraInfo\": \"Extra e-mail info2\"\n        }\n    ],\n    \"emailHtml\": \"<html> Hi, {{name}}, this is the email HTML body </html>\",\n    \"emailText\": \"Email text body\",\n    \"substitutionData\": {\n        \"name\": \"Recipient-1\"\n    },\n    \"attachments\": [{\n        \"data\": \"Q29uZ3JhdHVsYX2FuIGJhc2U2NCBkZWNvZGUh\",\n        \"name\": \"billing.pdf\",\n        \"type\": \"application/pdf\"\n    }]\n}",
  CURLOPT_HTTPHEADER => array(
    "authenticationtoken: <authenticationtoken>",
    "content-type: application/json",
    "username: <username>"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

POST https://api-messaging.movile.com/v1/email/send Content-Type: application/json

The body of the request must contain a JSON object in which the information is enveloped with the following fields. *field is required

Field Details Type
fromEmail* Email’s sender address. Ex. notificacion@domain.com String
fromName* Email’s sender name. Ex. Notification. String
replyTo Email address used to compose the email’s “Reply-To” header. String
subject Email subject line. String
campaignAlias Campaign name. String
recipients* Array of recipients.
correlationId Identifier generated by the client. String
emailAddress* Valid email address of a recipient. String
emailName Name of the recipient, associated to the emailAddress String
extraInfo Any extra info set by the user when the email was sent. String
emailHTML HTML content for the email’s text/html MIME part. String
emailText Text content for the email’s text/plain MIME part. String
substitutionData Mapping of tags, within {{}} marks, that should be replaced on html body.
attachments Array of attachment files.
data The content of the attachment as a Base64 encoded string. The string should not contain \r\n line breaks. String
name The filename of the attachment (for example, document.pdf). String
type The MIME type of the attachment; e.g., text/plain, image/jpeg, audio/mp3, video/mp4, application/msword, application/pdf, etc., including the charset parameter (ex: text/html; charset=“UTF-8”) if needed. The value will apply as-is to the Content-Type header of the generated MIME part for the attachment. String

SendEmail response

{
    "id": "abcd-1234-efgh-5678-ijkl-9999",
    "recipients": [
       {
          "correlationId": "5678",
          "id": "9i9j9k9l-5e6f7g8h-0i0j0k0l-1a2b3c4d"
       },
       {
          "correlationId": "5678",
          "id": "9i9j9k9l-5e6f7g8h-0i0j0k0l-1a2b3c4d"
       }
    ]
}

The response body will contain a JSON object with tracking information regarding the email request:

Field Details Type
id UUID generated for this email request. String
correlationId The same correlationId from the request. String
recipients Tag corresponding of a id and correlationId for every request recipient.

SearchEmail

SearchEmailStatus request

curl --request POST \
  --url https://api-messaging.movile.com/v1/email/status/search \
  --header 'authenticationtoken: rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF' \
  --header 'content-type: application/json' \
  --header 'username: felipe.cabrini@movile.com' \
  --data '{
    "correlationIds": ["1234", "5678", "7890"],
    "ids": ["1234-5678-9asd-fghj", "qwer-1234-asdf-0987",
              "zxcv-4567-ghjk-6789"],
    "startDate": "2017-04-27T10:00:00Z",
    "endDate": "2017-04-28T10:00:00Z"
}'
require 'uri'
require 'net/http'

url = URI("https://api-messaging.movile.com/v1/email/status/list")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["username"] = 'felipe.cabrini@movile.com'
request["authenticationtoken"] = 'rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF'
request["content-type"] = 'application/json'
request.body = "{\n\t\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}"

response = http.request(request)
puts response.read_body
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-messaging.movile.com/v1/email/status/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n\t\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}",
  CURLOPT_HTTPHEADER => array(
    "authenticationtoken: rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF",
    "content-type: application/json",
    "username: felipe.cabrini@movile.com"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import requests

url = "https://api-messaging.movile.com/v1/email/status/search"

payload = "{\n\t\"correlationIds\": [\"1234\", \"5678\", \"7890\"],\n\t\"ids\": [\"1234-5678-9asd-fghj\", \"qwer-1234-asdf-0987\",\n              \"zxcv-4567-ghjk-6789\"],\n\t\"startDate\": \"2017-04-27T10:00:00Z\",\n\t\"endDate\": \"2017-04-28T10:00:00Z\"\n}"
headers = {
    'username': "felipe.cabrini@movile.com",
    'authenticationtoken': "rHzrgp7Wigeo5sGmreBk95NYU4y92MPUjGvcdkbF",
    'content-type': "application/json"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

POST https://api-messaging.movile.com/v1/email/status/search Content-Type: application/json

Recovers information regarding a previously sent email, given its IDs, correlationIds and an interval date.

Field Details Type
ids* UUID generated for this email. Must correspond to the respective correlationId. String
correlationIds The same correlationId from the request. Must corresponds to the respective id. String
startDate Start date for search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String
endDate End date to search interval. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO String

Search EmailStatus response

[{
    "recipient": {
        "id": "1234-5678-9asd-fghj",
        "correlationId": "1234",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9638527410,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}, {
    "recipient": {
        "id": "qwer-1234-asdf-0987",
        "correlationId": "5678",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9876543210,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}, {
    "recipient": {
        "id": "zxcv-4567-ghjk-6789",
        "correlationId": "0987",
        "emailAddress": "recipient-1@movile.com",
        "emailName": "Recipient-1",
        "extraInfo": "Extra e-mail info1"
    },
    "fromEmail": "notificaction@movile.com",
    "fromName": "Notificactions",
    "createdAt": 12345678910,
    "createdDate": "2017-04-28T13:10:10.336Z",
    "sent": true,
    "sentStatusCode": 2,
    "sentStatus": "SENT_SUCCESS",
    "sentAt": 9876543210,
    "sentDate": "2017-04-28T13:10:10.336Z",
    "delivered": true,
    "deliveredStatusCode": 2,
    "deliveredStatus": "SENT_SUCCESS",
    "deliveredAt": 9876543210,
    "deliveredDate": "2017-04-28T13:10:10.336Z",
    "opened": true,
    "openedAt": 9638527410,
    "openedDate": "2017-04-28T13:10:10.336Z",
    "clicked": true,
    "clickedAt": 741258963,
    "clickedDate": "2017-04-28T13:10:10.336Z",
    "campaignId": 1,
    "campaignAlias": "demo1"
}]

The response is gonna be a JSON with all the information status about the sent emails, will contain the following fields:

Field Details Type
emailStatus Block for each email information.
recipient Block for recipient email information.
id The same id from the request.
correlationId The same correlationId from the request.
emailAddress Email address of the recipient.
emailName Name of the recipient, associated to the emailAddress.
extraInfo Any extra information.
fromEmail Email’s sender address. Ex. notificacion@domain.com
fromName Email’s sender name. Ex. Notification, Not reply, etc.
createdAt When the email was created. It is an Epoch Date. Long
createdDate When the message was created. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
sent Flag indicating if the email was sent. Boolean
sentStatusCode Sent status code. Check Sent Status Codes for more information. Long
sentStatus Sent status. String
sentAt When the email was sent. It is an Epoch Date. Long
sentDate When the email was sent.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
delivered Flag indicating if the email was delivered to the recipient. Boolean
deliveredStatusCode Delivered status code. Check Delivered Status Codes for more information. Long
deliveredStatus Delivered status. String
deliveredAt When the email was delivered. It is an Epoch Date. Long
deliveredDate When the email was delivered. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
open Flag indicating if the email was opened by the recipient. Boolean
openedAt When the email was opened. It is an Epoch Date. Long
openedDate When the email was opened. Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
clicked Flag indicating if the email was clicked by the recipient. Boolean
clickedAt When the email was clicked. It is an Epoch Date. Long
clickedDate When the email was clicked by the recipient.Format yyyy-MM-dd’T'HH:mm:ssZ. Date format with time and time zone ISO
campaignId Campaign identifier. Long
campaignAlias Campaign name. String

Status Codes

Sent Status Codes

A sent status code represents the status of a message passing through our system and being sent to the carrier.

Success codes

2 SENT_SUCCESS Sent to Movile successfully

Movile error codes

301 INTERNAL_ERROR Movile internal error

Delivered Status Codes

A delivered status code represents the status report that we receive from the server about the email.

Success codes

3 DELIVERED_SUCCESS Delivered to server successfully

Carrier error codes

103 NOT_DELIVERED Email accepted but has not delivered the e-mail.

Opened Status Codes

A open status code represents the e-mail opened by the customer.

Success codes

4 OPENED_SUCCESS Delivered to server successfully

Carrier error codes

104 NOT_OPENED Email accepted but has not opened by the customer

Clicked Status Codes

A clicked status code represents the status report when the customer clicked over the email. |||| |–|–|–| |5|CLICKED_SUCCESS|Clicked by the customer successfully|

Carrier error codes

104 NOT_CLICKED Email accepted but has not clicked by the customer

Configuring your on domain

To set your domain to send emails through our API you have to open a ticket to our Technical support sending a email to support.messaging@movile.com with the domain you gonna use.

It’s necessary to validate the ownership of that domain so you can use it, so it’s going to be requested the creation of a TXT DNS record with a DKIM key (all information is going to be provided by support team).

Warming UP

IP warming is the process of methodically adding campaign volume week-over-week to a new IP Address to establish a positive sending reputation with Internet Services Providers. (ISPs)

IP Warm-up Plan

During the Warm-up phase the more consistent you are with volume, frequency, complaint and bounce levels, the faster you will establish a positive sending reputation. If you send infrequently, anything less than weekly it will take more time to build a positive sender reputation.

Week 1 Daily Volume Notes
Day 1 200 • During weeks 1-2 send to the most
Day 2 500 active subscribers. 30 days active
Day 3 1,000
Day 4 2,000
Day 5 5,000 • During weeks 3-4 send to 60 days
Day 6 10,000 active subscribers.
Day 7 20,000
Week 2
Day 8 40,000 • Do not send to subscribers that have
Day 9 100,000 note opened or clicked in the past 90 days
Day 10 250,000 during the first 45 days of warm-up.
Day 11 500,000
Day 12 1,000,000
Day 13 2,000,000 • If warming above 5 Million do not send
Day 14 5,000,000 more than double the previous volume.