Email API
Last updated
Last updated
Technical Documentation: 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.
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:
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.
{
"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:
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.
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.
[{
"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.
A sent status code represents the status of a message that goes through our system and is sent to the carrier.
A delivered status code represents the status report we receive from the server about the email.
An opened status code represents the email opened by the customer.
A clicked status code represents the status report when the customer clicked over the email. |||| |–|–|–| |5|CLICKED_SUCCESS|Clicked by the customer successfully|
Field
Details
Data Type
UserName
Your username or email
String
AuthenticationToken
Your authentication token. Get yours here
String
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
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
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.
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
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
2
SENT_SUCCESS
Sent to Wavy successfully
301
INTERNAL_ERROR
Wavy internal error
3
DELIVERED_SUCCESS
Delivered to server successfully
103
NOT_DELIVERED
Email accepted but has not delivered the e-mail.
4
OPENED_SUCCESS
Delivered to server successfully
104
NOT_OPENED
Email accepted but has not opened by the customer
104
NOT_CLICKED
Email accepted but has not clicked by the customer