Follow

Email Sync API

Email Sync API

This REST API enables you to send email errors you detect or unsubscribe requests to Kahuna. Using this information, Kahuna can avoid sending email to users who can't or don't wish to receive them. In your API request, you identify each error with a reason and email address. Kahuna responds with results of processing each error you send.

As you send emails to your users, you probably receive back various types of email errors. Although you are not required to report these errors to Kahuna, when you do report them, you reduce the time and cost of running your campaigns. In addition, you help Kahuna to avoid sending emails to users who don't want them.

Using the Email Sync API, you can report users for whom the email failed and the reason for the failure. Kahuna uses the information to control who receives emails in future campaigns you run.

API Request

Request URI and Header

 

Request URI - HTTP POST

To target the production environment: https://tap-nexus.appspot.com/api/emailsync?env=p

To target the sandbox environment: https://tap-nexus.appspot.com/api/emailsync?env=s

 

Request Header

Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace are:

Secret Key: Available in Settings
API Key: Available in Settings
Request Body

The body of the request must contain a list of dictionaries, each of which contains exactly one reason, one email, and optionally one timestamp. You can make multiple requests concurrently.

Note: The API request body must be less than 10MB in size (approximately 100K emails).

Parameters
reason

 

Required. The reason can be one of the following:

  • unsub—recipient clicked on the unsubscribe link in an email.
  • hard_bounce—your email system detects that an email encountered a severe problem; for example, the email address no longer exists.
  • soft_bounce—your email system detects that an email encountered a minor problem; for example, the user's mailbox is full.
  • spam—your email system receives a message that an email is marked as spam.
  • reject—the user should be blacklisted.
  • invalid—the user is no longer a valid recipient.
  • blocked—delivery failure occurred during the email transmission.
email

Required. The email address.

timestamp

Optional. In seconds in Unix time (Epoch time).

Example
[
    {"reason" : "unsub","email" : "test@test.org"},
    {"reason" : "hard_bounce","email" : "doesnotexist@test.org"},
    {"reason" : "spam","email" : "test2@test.org","timestamp" : 1234567890}
]

API Response

The response for authentication requests is:

  • Non-200 if there are any errors that prevent all data from being processed.
  • 200 with accepted and rejected counts.

The response payload also includes an errors list if data is rejected.

Example
{
    "accepted" : 3,
    "rejected" : 0
} 

The following request contains errors.

[
    {"email" :  "test2@test.org"},
    {"reason" : "unsub","email" : "test@test.org"},
    {"reason" : "unknown","email" : "test@test.org"},
    {"reason" : "hard_bounce","email" : "doesnotexist@test.org"},
    {"reason" : "spam","email" : "test2@test.org","timestamp" : "1234567890"},
    {"reason" : "unknown","email" : "test@test.org","timestamp" : 1234567890}
]

The following shows a response to the request with errors above.

{
    "accepted" : 3,
    "rejected" : 3,
    "errors" : [
                ["Invalid Row",None,"test2@test.org",<server_time>],
                ["Invalid Reason Type","unknown","test@test.org",<server_time>],
                ["Invalid Row","spam","test2@test.org","1234567890"]
               ]
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments