Event

The Event Webhook notifies the specified endpoint of events that occur due to the mail sending and sending errors or blocking operations.

Notification to endpoint lists the event data and notify when either the notification interval (default every second) or the maximum number of events (default 100) is met.

API Settings

To use Event Webhook, you need to set the API from the management console.

Please refer to User Guide -> "API" -> Webhook and set the API.

Event

Event Webhook posts the following parameters to the endpoint.

Parameter	Required	Data Type	Description
api_key	No	ASCII	If the API key is set on the management console, the specified API key will be sent.
server_composition	Yes	UTF-8	Sends the name of the server configuration that this event occurred.
event_type	Yes	ASCII	Sends the type of this event.There are 3 types of events: deliveries, bounces and (blocks Pro).
event	Yes	UTF-8	The data defined for each event type is sent in JSON format.

Note

"blocks event" is a function available in the Pro plan. Please subscribe to the Pro plan to use it this function.

event/deliveries

This event occurs when an email is received from the mail relay source server and sent to the destination server.

JSON

{
"deliveries": [
    {
    "created": "2015-12-14 10:53:52",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "senderIp": "",
    "sourceIp": "10.0.24.10",
    "status": "queued",
    "subject": "sample email #1",
    "apiData" : "CMC00123"
    },
    {
    "created": "2015-12-14 10:53:53",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "sourceIp": "",
    "senderIp": "10.0.24.20",
    "status": "succeeded",
    "subject": "sample email #1",
    "apiData" : "CMC00123"
    },
    ...
]
}

Property	Description
created	Date and time when the delivery status for the email address was recorded(YYYY-MM-DD HH:mm:ss format)
messageId	Message-ID field value of the mail header
status	Represents the status of the email to sent delivery status
sourceIp	Connection IP of mail relay source server.Recorded if the delivery status is 'queued'.
senderIp	The IP used when sending this email to the destination server.Recorded if the delivery status is other than 'queued'.
returnPath	The 'envelope from' address used when sending the email.
from	The 'header from' address of this mail.
to	The 'envelope to' address used when sending the email.
subject	Subject of the mail
reason	SMTP response message. Recorded if the delivery status is 'failed' or 'deferred'.
apiData	The 'header value' of X-Api-Data given by the mail source application.

In case that the data you want to get has the long sending header value

Due to the specification of Email, long header values cannot be written as they are. Therefore, line breaks should be inserted in the header value as appropriate.

In the case of a header that extends over multiple lines, WSP characters are inserted at the beginning of the second and subsequent lines due to the header specifications. In this case, since JSON strings, etc. are not interpreted, spaces may be inserted in unintended places.

When using long header values in the headers parameter (X-Api-Data, etc.), it is recommended that JWT conversion, Base64 encoding, etc. be performed before sending the e-mail so that unintended WSP characters can be removed.

event/bounces

This event occurs when an email delivery fails.

JSON

{
"bounces": [
    {
    "from": "from1@example.com",
    "messageId": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E",
    "reason": "host unknown",
    "created": "2015-12-14 12:33:53",
    "status": "1",
    "to": "to1@example.com",
    "returnPath" : "env-from1@example.com",
    "subject" : "サービスに関するお知らせ",
    "apiData" : "CMC00123"
    },
    {
    "from": "from2@example.com",
    "messageId": "\u003dc9633d0-885f-11e5-8329-0638caaed3c7@node1\u003E",
    "reason": "Status:5.1.1 / X-Postfix; unknown user: \"to2@example.com\"",
    "created": "2015-12-14 12:33:53",
    "status": "2",
    "to": "to2@example.com",
    "returnPath" : "env-from2@example.com",
    "subject" : "サービスに関するお知らせ",
    "apiData" : "CMC00124"
    }
    ...
]
}

Property	Description
created	The date you received the bounce mail(YYYY-MM-DD HH:MM:SS format)
status	Represents for what reasons the mail delivery error status
from	The email address specified in 'from' of the mail header
to	The email address that sent this email
messageId	Message-ID field value of the mail header
reason	The body of the SMTP response message or bounce email used to determine the error status
returnPath	The 'envelope from' used when sending email.
subject	Subject of the email error occured.
apiData	The 'header value' of X-Api-Data given by the mail source application.

In case that the data you want to get has the long sending header value

Due to the specification of Email, long header values cannot be written as they are. Therefore, line breaks should be inserted in the header value as appropriate.

In the case of a header that extends over multiple lines, WSP characters are inserted at the beginning of the second and subsequent lines due to the header specifications. In this case, since JSON strings, etc. are not interpreted, spaces may be inserted in unintended places.

When using long header values in the headers parameter (X-Api-Data, etc.), it is recommended that JWT conversion, Base64 encoding, etc. be performed before sending the e-mail so that unintended WSP characters can be removed.

event/blocks

This event occurs when you register or delete an email address that you want to blocking.

JSON

{
"blocks": [
    {
    "created": "2015-12-14 10:53:52",
    "address" : "to1@example.com",
    "status": "registered"
    },
    {
    "created": "2015-12-14 10:53:52",
    "address" : "to2@example.com",
    "status": "deleted"
    },
    ...
]
}

Property	Description
created	The date when the blocked e-mail address registered or canceled.(YYYY-MM-DD HH:mm:ss format)
address	E-mail address that will be be operated.
status	The values and conditions of occurrence are shown below.

status value	conditions of occurrence
registered	This event will be notified If blocked is enabled due to the reasons such as the execution timing of the blocking has arrived,the execution is performed immediately from the screen or the target blocked email address is registered.
deleted	Notify you of the email address that has been blocked. You will be notified of this event when you do the following operation: - Cancel operation from the blocked screen - Transactional Email Blocks/delete API call - Transactional Email Blocks/cancel API call

Receiving the Delivery Error

As a model usage of Event Webhook, it is possible to detect and notify at real time when email sent by SMTP or API has a sending error Delivery errors can be detected by the following two methods.

bounced event

Receives a 'bounced event' to detect a send error in the Event Webhook. 'bounced' notifies the the error status that the result of receiving and analyzing bounce mail by the receiving server, and the destination email address in JSON format of event/bounces.To receive the 'bounced event', you need to receive a bounce email with Customers Mail Cloud.

failed event

'failed' notifies that 5xx-s eries of error occurred in the SMTP communication processing between the relay server and the destination server in JSON format of event/deliveries.
'failed event' can be notified without receiving a bounce email in Customers Mail Cloud.

Note

If Customers Mail Cloud is set to receive bounce mail and a delivery error occurs, the 'failed event' will occur first. After that,relay server generates and sends bounce emails.

The receiving server receives the bounce mail from the relay server and generate the 'bounced event'. Therefore, If you receive both 'failed' and 'bounced', you will receive duplicate data.