Webhooks
Webhooks are a powerful way for different software applications to communicate with each other in real-time. They allow the application to notify or transfer data to another application, based on the occurrence of certain events, thereby creating a workflow. These events can range from 'receiving a new mail' to 'sync completion' or any other significant action.
How Do They Work?
Webhooks work by setting up a URL (a webhook endpoint) in the receiving application. When the triggering event happens in the sending application, it sends a data payload to the URL. The receiving application then processes this data and can take action accordingly.
Webhooks in Mail360
When integrating webhooks with your application, Mail360 sends HTTP POST notifications to your specified URL for events like new mail, rename folder, sync completed, etc. This ensures your application stays synchronized with Mail360 activities, enabling timely responses or workflow triggers.
Scenarios
- New mail: When a new email arrives, a webhook can send a notification to the specified URL, providing the essential parameters about the incoming email. This notification will trigger a workflow in the connected application.
- Rename folder: When a folder is renamed, a webhook can sync the updated name across all integrated platforms to ensure consistency.
- Sync completed: Once syncing of emails for an account is completed, a webhook can notify the specified URL, with relevant details regarding the completion.
Table of Contents
Create a Webhook
To create a new webhook, follow these steps:
- Log in to your Mail360 account.
- Navigate to the Webhooks section. Click on Create. A create webhook window will pop up.
- Enter the Webhook URL where you wish to receive notifications for specific events.
- Provide a brief description of the webhook's purpose.
- Select the checkboxes corresponding to the events you want notifications for.
- Click on Save.
Webhook Events
Mail360 provides a range of events that can trigger webhooks, ensuring seamless real-time communication between integrated systems. The table below categorizes these events related to mail actions, folder operations, and synchronization, along with their corresponding values in the sample data.
Entity | Event/Action Name | Event Value | Event Description |
Folder | Add folder | addFolder | A new folder has been created. |
Delete folder | deleteFolder | An existing folder has been deleted. | |
Empty folder | emptyFolder | All emails in the folder have been deleted. | |
Folder read | folderRead | All emails in the folder are marked as read. | |
Move folder | moveFolder | An existing folder is moved to another location. | |
Rename folder | renameFolder | An existing folder has been renamed. | |
Apply label | applyLabel | A specific label has been applied to an email. | |
Copy mail | copyMail | The email has been copied to a different location. | |
Mark flagged | markFlagged | The email has been marked with a flag. | |
Move mail | moveMail | The email has been moved to a different location. | |
New mail | newMail | A new email has been received. | |
Remove label | removeLabel | A specific label has been removed from the email. | |
Sync | Sync completed | syncCompleted | The sync has been successfully completed. |
Sync failure | fetchFailure | The sync has failed. |
Sample Webhook Data
The sample webhook data represents the specific payload structure you can expect to receive. When a particular event occurs, Mail360 will send an HTTP POST request, carrying a payload that mirrors the sample data, to the designated URL you have specified.
Mail360 provides a way to view the sample format of the data/ payload that will be sent to your specified URL when the events you have selected for notifications occur. To view the sample format of the data/payload, follow the following steps:
- Log in to your Mail360 account.
- Navigate to the Webhooks section. Click on Create. A create webhook window will pop up.
- Click the Sample Webhook button, located at the bottom right-hand side corner of the Create Webhook page.
Refer below for a brief description of some of the key parameters found in these Sample data:
- Account Information
- account_key: A unique key associated with an account.
- Email Fields
- bcc_address: Email address in Bcc field.
- cc_address: Email address in Cc field.
- from_address: Sender's email address.
- to_address: Receiver's email address.
- Email properties
- has_attachment: A flag indicating whether the email contains attachments.
- header_message_id: A unique identifier found in the email header.
- message_id: A unique identifier assigned to the message.
- message_info_json: A JSON object containing detailed information about the message.
- read_status: Indicates whether the email has been read.
- received_time: The timestamp when the email was received.
- return_path: The email address for bounce-backs or delivery errors.
- send_time_in_gmt: The timestamp of when the email was sent in GMT.
- sender: The username or email address of the person who sent the email.
- size: The size of the email, typically measured in bytes or kilobytes.
- summary: A brief overview of the email's content.
- thread_id: A unique identifier representing the conversation thread of the email.
- Email Actions
- event: Specifies the type of event that occurred.
- failure_reason: Provides a reason for a failure event.
- flag: The flag applied to an email.
- operation: Specifies the type of operation performed.
- tag: The tag applied to an email.
- Folder Details
- folder_id: A unique identifier for a folder.
- folder_name: The name of the folder.
- folder_type: Specifies the type of folder.
- parent_folder_id: The folder ID of the parent folder.
- previous_folder_id: The folder ID of the previous folder.
View Webhooks
To view the list of webhooks available in Mail360, follow the below steps:
- Log in to your Mail360 account.
- Navigate to the Webhooks section. Click on Create. A list of webhooks available will be displayed here.
View Logs
The View Logs section offers a detailed log of webhooks activated in response to events associated with that specific webhook. Each log entry provides details such as the time, the triggered URL, and the event that occurred, along with key response data (**note: some response data may not be available).
To view logs of webhook logs associated with a specific URL:
- Hover over the specific webhook.
- Click on View Logs.
- To inspect the parameters contained in the request body:
- Click on the expand icon in the parameter section.
Updating a Webhook
To modify a webhook, follow these steps:
- Log in to your Mail360 account.
- Navigate to the Webhooks section, hover over the webhook you aim to update and click on the Edit icon.
- In the Edit Webhook window, make your desired changes.
- Click on Update.
Deleting a Webhook
To delete a webhook, follow the following steps:
- Log in to your Mail360 account.
- In the Webhooks section, hover over the webhook you wish to delete and click the Delete icon.
- In the deletion confirmation dialog that appears, confirm your decision by clicking Yes.