Email API
Technical Documentation: Email API.
Email API
This API allows you to automatize both single and bulk message requests and the retrieval of sent status through its endpoints. It uses HTTP protocol with TLS and accepts GET requests with query string parameters and POST requests with JSON parameters.
User Authentication
In order to successfully use our API, you are required to present a valid username - or email - and the associated token authentication. While creating the request, you have to provide the following parameters on the headers:
Field
Details
Data Type
UserName
Your username or email
String
Connection Details
Hostname
api-messaging.wavy.global
APIs
SendEmail /v1/email/send SearchEmail /v1/email/status/search ListEmail /v1/email/status/list
Port
443 (https)
Protocol
HTTPS (TLS encryption)
Authentication
username + token
SendEmail
SendEmail request
curl --request POST \
--url https://api-messaging.wavy.global/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@wavy.global",
"emailName": "Recipient-1",
"extraInfo": "Extra e-mail info1",
"substitutionData": {
"name": "Recipient-1"
}
},
{
"correlationId": "567",
"emailAddress": "recipient-2@wavy.global",
"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"
}]
}'
POST https://api-messaging.wavy.global/v1/email/send Content-Type: application/json
The request body must contain a JSON object in which information are enveloped with the following fields. Fields with a * are required.
Field
Details
Type
fromEmail*
Email sender’s address. E.g. notification@domain.com
String
fromName*
Email sender’s name. E.g. 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 customer.
String
emailAddress*
Valid email address of a recipient.
String
emailName
Name of the recipient, associated with 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 related to 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 to an id and correlationId for every request recipient.
SearchEmailStatus request
Example:
{
"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"
}
POST https://api-messaging.wavy.global/v1/email/status/search Content-Type: application/json
Retrieves information on a previously sente mail, given its IDs, correlationIds, and a date interval.
Field
Details
Type
ids*
UUID generated for this email. Must correspond to the respective correlationId.
String
correlationIds
The same correlationId from the request. Must correspond 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
ListEmailStatus request
POST https://api-messaging.wavy.global/v1/email/status/list Content-Type: application/json
Retrieves information on a previously sente mail, considering its user and token. This method returns all emails that haven’t yet been checked.
List and 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": "Notifications",
"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": "Notifications",
"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": "Notifications",
"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"
}]
Retrieves information on a previously sent email, considering its user and token. This method returns all emails not previously queried.
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 with the emailAddress.
extraInfo
Any extra information.
fromEmail
Email sender’s address. E.g. notification@domain.com
fromName
Email sender’s name. E.g. 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 that goes through our system and is sent to the carrier.
Success codes
2
SENT_SUCCESS
Sent to Wavy successfully
Wavy error codes
301
INTERNAL_ERROR
Wavy internal error
Delivered Status Codes
A delivered status code represents the status report 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
An opened status code represents the email 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
Last updated