Webhook

Webhook provides an interface to post the event data that occures during sending and receiving emails to the specified endpoint via HTTP. Please check the API reference for Webhook usage instructions.

This section explains Webhook operating settings and log references.


Event Webhooks

Send email delivery statuses to endpoints in real time.

Settings

Click the Menu->API settings at top right of the magament console screen.

Click the Webhook tab.

Click the Event tab.

Click the Settings tab.

Event settings

Input the below items:

Items Required Description
Endpoint URL Yes To receive events input the endpoint URL starting with https://
Bounces No Check the box if you want to receive the error statuses.
Deliveries No Check the box if you want to receive the delivery statuses.
Blocks No Check the box if you want to receive the operation events for Delivery Blocking.
Version Yes Specifies the version of the event data sent to the endpoint.
Time Zone Yes Specifies the time zone to apply to the date and time information included in event data.
Content Type No If you check the use JSON format, event data will be sent in the application/json content type. This can be specified if you select version 2 or later in the Version.

Pro

To use `Delivery Blocking` please subscribe to the Pro plan.

Bounces

Event Type Description
Bounced Analyzes the SMTP errors and bounced emails. Sends notifications with email addresses which have experienced a sending error with the included error status. Monitor this event if you want to control sending errors in real time.

Deliveries

Event Type Description
Queued Sends notifications when emails have been received from the originating mail relay server.
Succeeded Sends notifications when SMTP communications with destination mail servers have succeed.
Failed Sends notifications when SMTP communications with destination mail servers have failed.
Deferred Sends notifications when emails have been placed in the resend queue due to a temporary error.

Blocks

Event Type Description
Registered If the Delivery Blocking is valid, sends a notification of the email address that was blocked.
Deleted Sends a notification with emails that have canceled their blocking request.
Cancel from the blocked list's screen using the:
- Transactional Email Blocks/delete API call
- Transactional Email Blocks/cancel API call

You can set the below items when you click the Advanced button.

Event Advanced

Security

You can send basic authentication credentials or key information that your application requires when the webhooks connect to the endpoint.

Items Required Description
Username No Input the user name if the endpoint is capable of using basic access authentication.
Password No Input the password you wish to use for basic access authentication.
Password confirmation No Input your desired password a second time.
API Key No Input the secret key you wish to pass to the endpoint. If you check the Authorization: Use Bearer header the API key will be set as a Bearer token in the Authorization header of the HTTP request. Sending data does not include the API key in this case.
Basic Authentication and Authorization: Bearer headers cannot be used together.

Handling Notifications

You can set the event notification actions. Event's notifications are sent at every set notification interval or when the maximum number of events is exceeded.

Items Required Description
Notification interval No Specifies the event notifcation interval in seconds. (1-600second)
Maximum number of events No Specifies the maximum number of events to be notified in one request. (100-10000)
Time out No Specifies the time that the system will wait for a response when connecting to an endpoint in seconds. (1-999 seconds)

When you click the Save button, the event notification settings will be saved in the management console. To have the saved reflect settings on the email server follow these instructions.


Logs

It is possible to search the webhook event's activity logs.

Click the Log tab.

Event log

Then, click the Search button to search and display the relevant log(s).

If queries exceed a 100 or more results the first 100 will be displayed. Include the time period and status conditions in your search to narrow down the target data.
If queries exceed 10 or more results the exceeding results will be sent to succeeding pages. To navigate results exceeding the first 10 use the top right page navigation tabs.
Display Name Description
Date Displays the log's date.
Host Name Displays the host name of the server that recorded the log.
Endpoint URL Displays the URL of the endpoint that was set during the time the log was recorded.
Status Displays the statuses: queued, succeeded, deferred or failed. For more information please refer to event statuses.

Event Status

The event status will be recorded as the result of the endpoint post process from a target notification's mail delivery event.

Status   Description
queued This status occurs when targeted notifications of email delivery events are triggered.
succeeded Post to endpoint is successful.
failed This status occurs when an email has passed the resend interval or when the post has failed due to a permanent error on the recpient's server.
deferred Post has failed due to temporary error and has re-sent.

Log Details

You can view additional detailed information by clicking on the host name link in the log list.

Event log details

Display Name       Description
Date Displays the recorded date of log(s).
Status Displays the status.
Host Name Displays the host name of the server that record the log(s).
Endpoint URL Displays the endpoint URL that was set at the time the log(s) was recorded.
Error Reason Displays the error reason if the status is deferred or failed.

Downloading the Logs

Click the Download button to download the log search results into a CSV file.

Event log download

You can download all the data even if results exceed 100+ queries. The character code of the CSV file is `UTF-8` and the line feed code is `LF`.

The below items will be output to the CSV file:

Item Name Description
received Displays the recorded date of the log(s).
status Status
hostName Displays the host name of the server that recorded the log(s).
endpointUrl Displays the endpoint URL that was set at the time the log(s) was recorded.
reason Displays the error reason if the status is deferred or failed.

Inbound Webhooks

This sections explains sending From, To, Subject, Body, etc as parsed data to the endpoint after receiving an email.

You are required to give permission to receive inbound emails. To do this to go: settings -> receiving server -> receive inbound and give permission to the domain of the destination email address.

Settings

Click the Menu->API settings at the top right of management console.

Click the Webhook tab.

Click the Inbound tab.

Click the Settings tab.

inbound list

You can specify a combination of values and the mail header as conditions for receiving email.

Adding inbound webhooks

Input fields and additional dialogue will be displayed when you click the Add button.

notification settings

Input the below items:

Item       Required Description
Notification name Yes Input the name that identifies your inbound emails receiving settings.
EndpointURL Yes To receive inbound notifications, input the endpoint URL starting with https://.
Notification Terms Yes Specify the conditions for sending the received email to the endpoint. When you click the + button the notification conditions will be added. Notification conditions are additive - all conditions must be matched as AND.
Content Type No When you check use JSON format box, inbound notifications will be sent in the application/json content type. Email attachments are not notified in JSON format.

Specify the below values for notification terms:

Items    Value
Header Name If you specify "To"、envelope-to will be evaluated. You can also specify additional fields from the mail header such as From and Subject. Email headers are not case sensitive and will match regardless.
header value Input the regex to match the header value. For more information please refer to common specifications.

You can set the following items by clicking Advanced:

Inbound Advanced

Security

You can send basic authentication credentials or key information that your application requires when the webhooks connect to the endpoint.

Items Required Description
Username No Input the user name if the endpoint is capable of using basic access authentication.
Password No Input the password you wish to use for basic access authentication.
Password confirmation No Input your desired password a second time.
API Key No Input the secret key you wish to pass to the endpoint. If you check the Authorization: Use Bearer header the API key will be set as a Bearer token in the Authorization header of the HTTP request. Sending data does not include the API key in this case.
Basic Authentication and Ahthorization: Bearer headers cannot be used together.

Notification Actions

You can set the notification actions of inbound emails.

Items       Required Description
Retry interval No Specifies the retry interval when there is a response error or when you can't connect to the endpoint in seconds.(10-600 seconds)
Retry period No Specifies the retry period in days.(1-10days)
Time Out No Specifies the time that the system will wait for a response when connecting to an endpoint in seconds. (1-999 seconds)
Conditions No Mark as checked if you want to stop the operation without deleting the notification conditions.

When you click the Save button, the event notification settings will be saved in the management console. To have the saved reflect settings on the email server follow these instructions.

Deleting

A confirmation popup will be displayed when you click the Delete button in the inbound settings list. Input the password for this account and click the Delete button once more to finalize the deletion of the inbound settings.

Log Settings

Pro

Domains not enabled for accepting email traffic in the management console will output rejection logs in CMC with the recipient's email address.

A huge amount of logs may be output because domain mismatched logs are output even when receiving spam mail. Because of this, we recommend for receiving domains permitted by CMC (inbound) to not set logs to be output with the exception of initial setup and operational confirmation circumstances.

Displays the log dialog when you click log settings.

Inbound Log-setting

When you click the Save button, the event notification settings will be saved in the management console. To have the saved reflect settings on the email server follow these instructions.


Log

It is possible to search the inbound webhook event's activity logs.

Click the Log tab.

Inbound log

Click the Search button to search to display the relevant log(s).

If queries exceed a 100 or more results the first 100 will be displayed. Include the time period and status conditions in your search to narrow down the target data.
If queries exceed 10 or more results the exceeding results will be sent to succeeding pages. To navigate results exceeding the first 10 use the top right page navigation tabs.
Display Name       Description
Date Displays the recorded date of the log(s).
Destination Address Displays the destination address of the received email.
From address Displays the from address in the header of the received email.
Filter Name Displays the notification name of applied receiving settings.
Status Displays one of the following: queued, succeeded, deferred, failed, or denied. For more information please refer to Inbound status

Inbound Status

The target notification’s email receipts and endpoint post results are recorded as the status.

Status   Description
queued Received the notification target mail.
succeeded Posting to endpoint was succesful.
failed The received mail has discarded because resend period is expired or the post has failed due to a permanent error.
deferred Post is failed due to temporary error and has resend.
denied Email receiving has recejted due to a mismatch in the notification conditions or the destination email address is not set in the receiving permission domain (inbound).

Log Details

You can view additional detailed information by clicking on the destination address link in the log list.

Inbound log details

Display Name       Description
Date Displays the recorded date of log.
Status Displays the status
Host Name Displays the host name of the server that recorded the log.
From Address Displays the from address in the header of the received email
Destination Address Displays the destinatoin email address of the received mail.
Message ID Displays the Message-ID in the header of the received mail.
Filter Name Displays the notification name of saved email receiving settings.
Error Reason Displays the error reason if the status is deferred, failed, or denied.

Downloading the Log

Click the Download button to download the log search results into a CSV file.

Inbound log download

You can download all the data even if results exceed 100+ queries. The character code of the CSV file is `UTF-8` and the line feed code is `LF`.
The below items will be output to the CSV file:
Item name Description
received Recorded date of the log
status Status
from From address in the header of received emails
to Destination address of received emails
hostName Host name of the server that recorded the log(s)
messageId Message-Id on the mail header of the received email
filterName Notification name of applied receiving settings
reason Error reason