📢 Webhooks module Email API

Receive notifications of your email events via webhooks.

Enroll method

Enrolls the user to receive event notifications via webhooks.

Usage

modular.ts

import { MailChannelsClient, Webhooks } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const webhooks = new Webhooks(mailchannels)

const { success, error } = await webhooks.enroll("https://example.com/api/webhooks/mailchannels")

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { success, error } = await mailchannels.webhooks.enroll("https://example.com/api/webhooks/mailchannels")

Params

• endpoint string required: The URL to receive event notifications. Must be no longer than 8000 characters.

Response

• success boolean guaranteed: Whether the operation was successful.
• error string | null nullable

List method

Lists all the webhook endpoints that are enrolled to receive event notifications.

Usage

modular.ts

import { MailChannelsClient, Webhooks } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const webhooks = new Webhooks(mailchannels)

const { data, error } = await webhooks.list()

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.webhooks.list()

Response

• data string[] | null nullable
• error string | null nullable

Delete method

Deletes all registered webhook endpoints for the user.

Usage

modular.ts

import { MailChannelsClient, Webhooks } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const webhooks = new Webhooks(mailchannels)

const { success, error } = await webhooks.delete()

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { success, error } = await mailchannels.webhooks.delete()

Response

• success boolean guaranteed: Whether the operation was successful.
• error string | null nullable

Signing Key method

Retrieves the public key used to verify signatures on incoming webhook payloads.

Usage

modular.ts

import { MailChannelsClient, Webhooks } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const webhooks = new Webhooks(mailchannels)

const { data, error } = await webhooks.getSigningKey('key-id')

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.webhooks.getSigningKey('key-id')

Params

• keyId string required: The ID name of the signing key.

  TIP

  The keyId can be found in the signature-input request header of the webhook notification.

Response

• success boolean guaranteed: Whether the operation was successful.
• data object | null nullable
  • key string guaranteed
• error string | null nullable

Validate method

Validates whether your enrolled webhook(s) respond with an HTTP 2xx status code. Sends a test request to each webhook containing your customer handle, a hardcoded event type (test), a hardcoded sender email (test@mailchannels.com), a timestamp, a request ID (provided or generated), and an SMTP ID. The response includes the HTTP status code and body returned by each webhook.

Usage

modular.ts

import { MailChannelsClient, Webhooks } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const webhooks = new Webhooks(mailchannels)

const { data, error } = await webhooks.validate('optional-request-id')

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.webhooks.validate('optional-request-id')

Params

• requestId string optional: Optional identifier in the webhook payload. If not provided, a value will be automatically generated.

  NOTE

  The request id must not exceed 28 characters.

Response

• data object | null nullable
  • allPassed boolean guaranteed: Indicates whether all webhook validations passed
  • results object[] guaranteed: Detailed results for each tested webhook, including whether it returned a 2xx status code, along with its response status code and body.
    • result "passed" | "failed" guaranteed: Indicates whether the webhook responded with a 2xx HTTP status code.
    • webhook string guaranteed: The webhook that was validated.
    • response object guaranteed: The HTTP response returned by the webhook, including status code and response body. A null value indicates no response was received. Possible reasons include timeouts, connection failures, or other network-related issues.
      • body string optional: Response body from webhook. Returns an error if unprocessable or too large.
      • status number guaranteed: HTTP status code returned by the webhook.
• error string | null nullable

Type declarations

class Webhooks {
  constructor (protected mailchannels: MailChannelsClient);
  async enroll (endpoint: string): Promise<SuccessResponse>;
  async list (): Promise<WebhooksListResponse>;
  async delete (): Promise<SuccessResponse>;
  async getSigningKey (id: string): Promise<WebhooksSigningKeyResponse>;
  async validate (requestId?: string): Promise<WebhooksValidateResponse>;
}

All type declarations

Responses

interface DataResponse<T> {
  data: T | null;
  error: string | null;
}

interface SuccessResponse {
  success: boolean;
  error: string | null;
}

List type declarations

type WebhooksListResponse = DataResponse<string[]>;

Signing Key type declarations

type WebhooksSigningKeyResponse = DataResponse<{
  key: string;
}>;

Validate type declarations

type WebhooksValidateResponse = DataResponse<{
  allPassed: boolean;
  results: {
    result: "passed" | "failed";
    webhook: string;
    response: {
      body?: string;
      status: number;
    } | null;
  }[];
}>;

Source

Source • Playground • Docs