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

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

2. Click the Webhook tab.

3. Click the Event tab.

4. Click the Settings tab.

   

5. 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 Pro	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 notermation 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.

Warning

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.

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.

Warning

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

1. Click the Log tab.

   

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

Note

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.

Note

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.

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.

Note

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.

about condigions for judgement of spam mail regarding permitted domains for receiving

In the following cases, the email will be judged as spam mail and rejected.

1. If the header from is a permitted domain of the receiving server

   Even though the email is supposed to be received from an external source, it is judged to be suspicious because the from field is in thename of the recipient's own domain.

2. If the header from and to are the same email address

   This is also judged as suspicious email addressed to you.

Settings

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

2. Click the Webhook tab.

3. Click the Inbound tab.

4. Click the Settings tab.

   

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

Adding inbound webhooks

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

   

2. 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.

3. 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.

4. You can set the following items by clicking 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.

Warning

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

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

Note

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.

1. Displays the log dialog when you click log settings.

   

2. 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.

1. Click the Log tab.

   

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

Note

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.

Note

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.

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

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

   

   Note

   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.

2. 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