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 |
AuthenticationToken | Your authentication token. Get yours here | 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