📥 Users module Inbound API

Manage your MailChannels Inbound recipient users.

Create method

Create a recipient user.

Usage

modular.ts

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

const mailchannels = new MailChannelsClient('your-api-key')
const users = new Users(mailchannels)

const { data, error } = await users.create('name@example.com', {
  admin: true
})

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.users.create('name@example.com', {
  admin: true
})

Params

• email string required: The email address of the user to create.
• options UsersCreateOptions optional: Options for creating the user.
  • admin boolean optional: Flag to indicate if the user is a domain admin or a regular user.

    NOTE

    If admin is not set, defaults to false.

  • filter boolean | "compute" optional: Whether or not to filter mail for this recipient. There are three valid values. Defaults to compute.

    TIP

    Possible values are false, true, and compute.

    • false: Filtering policy will be applied to messages intended for this recipient. If this would exceed the protected-addresses limit, return an error.
    • true: Filtering policy will not be applied to messages intended for this recipient.
    • compute: Filtering policy will be applied to messages intended for this recipient. If this would exceed the protected-addresses limit, filtering policy will not be applied, and no error will be returned.
  • listEntries object optional: Safelist and blocklist entries to be added.
    • blocklist string[] optional: A list of items to add to the blocklist.
    • safelist string[] optional: A list of items to add to the safelist.

Response

• data object | null nullable
  • email string guaranteed
  • roles string[] guaranteed
  • filter boolean optional
  • listEntries object[] guaranteed
    • item string guaranteed
    • type "domain" | "email_address" | "ip_address" guaranteed
    • action "safelist" | "blocklist" 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.

Add List Entry method

Add an entry to a recipient user blocklist or safelist.

Usage

modular.ts

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

const mailchannels = new MailChannelsClient('your-api-key')
const users = new Users(mailchannels)

const { data, error } = await users.addListEntry('name@example.com', {
  listName: 'safelist',
  item: 'name@domain.com'
})

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.users.addListEntry('name@example.com', {
  listName: 'safelist',
  item: 'name@domain.com'
})

Params

• email string required: The email address of the recipient whose list will be modified.
• options ListEntryOptions required: Add list entry options.
  • listName "blocklist" | "safelist" | "blacklist" | "whitelist" required: The list to add the item to.
  • item string required: The item to add to the list. This can be a domain, email address, or IP address.

Response

• data ListEntry | null nullable
  • action "blocklist" | "safelist" guaranteed
  • item string guaranteed
  • type "domain" | "email_address" | "ip_address" 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.

List Entries method

Get recipient list entries.

Usage

modular.ts

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

const mailchannels = new MailChannelsClient('your-api-key')
const users = new Users(mailchannels)

const { data, error } = await users.listEntries('name@example.com', 'safelist')

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.users.listEntries('name@example.com', 'safelist')

Params

• email string required: The email address of the recipient whose list will be fetched.
• listName "blocklist" | "safelist" | "blacklist" | "whitelist" required: The name of the list to fetch.

Response

• data ListEntry[] | null nullable
  • action "blocklist" | "safelist" guaranteed
  • item string guaranteed
  • type "domain" | "email_address" | "ip_address" 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.

Delete List Entry method

Delete item from recipient list.

Usage

modular.ts

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

const mailchannels = new MailChannelsClient('your-api-key')
const users = new Users(mailchannels)

const { success, error } = await users.deleteListEntry('name@example.com', {
  listName: 'safelist',
  item: 'name@domain.com'
})

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.users.deleteListEntry('name@example.com', {
  listName: 'safelist',
  item: 'name@domain.com'
})

Params

• email string required: The email address of the recipient whose list will be modified.
• options ListEntryOptions required: Add list entry options.
  • listName "blocklist" | "safelist" | "blacklist" | "whitelist" required: The name of the list to remove an entry from.
  • item string required: The list entry which should be removed. This can be a domain, email address, or IP address.

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.

Type declarations

class Users {
  constructor (protected mailchannels: MailChannelsClient);
  async create (email: string, options?: UsersCreateOptions): Promise<UsersCreateResponse>;
  async addListEntry (email: string, options: ListEntryOptions): Promise<ListEntryResponse>;
  async listEntries (email: string, listName: ListNames): Promise<ListEntriesResponse>;
  async deleteListEntry (email: string, options: ListEntryOptions): Promise<SuccessResponse>;
}

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;
}

Create type declarations

interface UsersCreateOptions {
  admin?: boolean;
  filter?: boolean | "compute";
  listEntries?: {
    blocklist?: string[];
    safelist?: string[];
  };
}

type UsersCreateResponse = DataResponse<{
  email: string;
  roles: string[];
  filter?: boolean;
  listEntries: {
    item: string;
    type: "domain" | "email_address" | "ip_address";
    action: "safelist" | "blocklist";
  }[];
}>;

List Entry type declarations

type ListNames = "blocklist" | "safelist" | "blacklist" | "whitelist";

interface ListEntryOptions {
  listName: ListNames;
  item: string;
}

interface ListEntry {
  action: Extract<ListNames, "blocklist" | "safelist">;
  item: string;
  type: "domain" | "email_address" | "ip_address";
}

type ListEntryResponse = DataResponse<ListEntry>;

type ListEntriesResponse = DataResponse<ListEntry[]>;

Source

Source • Playground • Docs