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.

　　Note

　　　"blocks event" is a function available in the Business / Enterprise / OEM / Pro
　　　plan. Please subscribe to the Business / Enterprise / OEM / 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"
    },
    ...
]
}

　　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"
    }
    ...
]
}

　　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（Business / Enterprise / OEM / Pro）

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"
    },
    ...
]
}

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.