Please Note: X-APIHEADER is the value passed in token_to, token_cc, token_bcc

Sent Webhook

Email has been successfully delivered to the receiving server:

Sample sent webhook data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15536250111702803,
			"RESPONSE": " - 2.0.0 (success)",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1553681625,
			"FROMADDRESS": "[email protected]",
			"EVENT": "sent",
			"MSIZE": 2155,
			"X-APIHEADER": "UNIQUEID",
			"TAGS": "mytag1"
	}
]

Open Tracking Webhook

Recipient has opened the email

Sample open tracking webhook data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15543162084122748,
			"RESPONSE": "",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1554375863,
			"FROMADDRESS": "[email protected]",
			"EVENT": "opened",
			"MSIZE": 6368,
			"USERAGENT": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)",
			"TAGS": "tag1",
			"X-APIHEADER": "xapi1",
			"IPADDRESS": "64.233.173.70"
	}
]

Click Tracking Webhook

The Click Tracking webhook is a way by which Netcore Email API can notify your application when a recipient clicked a tracked link in your email. This can be useful in a variety of situations, such determining effectiveness of your transactional emails:

  • Customers clicking specific CTAs should be treated as hot lead in your application and call to be scheduled with your sales team.
  • Can customers easily identify a reset-password link?
  • Or, simply for auditing purposes.

Sample click tracking webhook data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15543162084122748,
			"RESPONSE": "",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1554376443,
			"FROMADDRESS": "[email protected]",
			"EVENT": "clicked",
			"MSIZE": 6368,
			"USERAGENT": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
			"TAGS": "tag1",
			"X-APIHEADER": "xapi1",
			"URL": "https://www.pepipost.com",
			"IPADDRESS": "123.201.124.74"
	}
]

Bounced Tracking Webhook

One of the reasons you send emails through Netcore Email API is to handle all of the possible bounces that email servers can return. And once these bounces are available on Netcore Email API, you might be needing the same in real time to take further actions. This is possible by enabling Bounce Webhooks, which will give you live stream of bounces in a easy to understand JSON format.

Based on the type of bounce, it can be further classified into:

  1. Hard Bounce: Receiving server could not or would not accept message because of multiple reasons like receiving server is not reachable, email address doesn’t exists etc. All such reasons are a part of Hard Bounce which will lead to suppression of the email address from your Netcore Email API account.

  2. Soft Bounce: There are other set of bounces which are treated as Soft Bounce, e.g. Mailbox full. These are temporary bounces.

Hard Bounce data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15543162088093688,
			"RESPONSE": "smtp;550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient’s email address for typo or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 z130si23626456iod.1",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1554378741,
			"FROMADDRESS": "[email protected]",
			"EVENT": "bounced",
			"MSIZE": 6364,
			"TAGS": "tag1",
			"X-APIHEADER": "xapi1",
			"BOUNCE_TYPE": "HARDBOUNCE",
			"BOUNCE_REASON": "email account that you tried to reach does not exist",
			"BOUNCE_REASONID": 77
	}
]

Soft Bounce data

An example of the full JSON that would be POSTed to your webhook URL is:

[
{
    "TRANSID":15543162084122748,
    "RESPONSE":"Host or domain name not found. Name service error for name=tesjsdfj.com type=A: Host not found",
    "EMAIL":"[email protected]",
    "TIMESTAMP":1547719884,
    "FROMADDRESS":"[email protected]",
    "EVENT":"bounced",
    "MSIZE":3276,
    "TAGS":"tag1",
    "X-APIHEADER":"xapi1",
    "BOUNCE_REASON":"UnknownReason",
    "BOUNCE_TYPE":"SOFTBOUNCE",
    "BOUNCE_REASONID": 201
}
]


Dropped Request Webhook

Users who have already unsubscribed in past or blacklisted because of hard bounce/Spam complaints will be treated as dropped. And, no further email communication is allowed on these types of ids. Sample POST Output:

Sample dropped request webhook data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15536250111702803,
			"RESPONSE": "Recipient Dropped :: status not confirmed",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1553681625,
			"FROMADDRESS": "[email protected]",
			"EVENT": "dropped",
			"MSIZE": 2155,
			"X-APIHEADER": "UNIQUEID",
			"TAGS": "mytag1"
	}
]

Invalid Request Webhook

All API requests with syntactically incorrect email ids will be treated as Invalid and no further processing will be done on such ids. You can capture all such invalid events in real time and try correcting them offline.

Sample invalid request webhook data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15543162086014008,
			"RESPONSE": "Invalid Email Address",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1554377297,
			"FROMADDRESS": "[email protected]",
			"EVENT": "invalid",
			"MSIZE": 6368,
			"TAGS": "tags1",
			"X-APIHEADER": "xapi1"
	}
]

Unsubscribe Tracking Webhook

Recipient clicked on the unsubscribe management link

Sample unsubscribe webhook data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15543162084122748,
			"RESPONSE": "Your emails are not relevant to me",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1554376733,
			"FROMADDRESS": "[email protected]",
			"EVENT": "unsubscribed",
			"MSIZE": 6368,
			"USERAGENT": "Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Firefox/60.0",
			"TAGS": "tag1",
			"X-APIHEADER": "xapi1",
			"IPADDRESS": "123.201.124.74"
	}
]

Spam Complaint Webhook

A Abuse complaint is recorded when a user clicks Report Spam or Mark as Spam from their email clients like Yahoo, Hotmail, AOL.

Once a spam complaint is recorded, Netcore Email API suppresses the email address by adding the address under the Suppression List of your account. While you will have the rights to whitelist the email address again for receiving emails, but this is not a recommended practice.

In the email industry, spam complaints are a clear metric to determine abuse and poor sending practices. It’s important that we all take these complaints seriously to ensure the best of the delivery.

Sample spam complaint webhook data

An example of the full JSON that would be POSTed to your webhook URL is:

[
	{
			"TRANSID": 15536250111702803,
			"RESPONSE": "",
			"EMAIL": "[email protected]",
			"TIMESTAMP": 1553681625,
			"FROMADDRESS": "[email protected]",
			"EVENT": "spam",
			"MSIZE": 2155,
			"X-APIHEADER": "UNIQUEID",
			"TAGS": "mytag1"
	}
]