📢 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 ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request.

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 ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request.

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 ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request.

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 ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request.

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 ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request.

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

Response type declarations

interface ErrorResponse {
  message: string;
  statusCode: number | null;
}

type DataResponse<T> = {
  data: T;
  error: null;
} | {
  data: null;
  error: ErrorResponse;
};

interface SuccessResponse {
  success: boolean;
  error: ErrorResponse | 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