MailChannels Node.js SDK

Appearance

🪪 Sub-Accounts module Email API ​

Manage your sub-accounts associated with your MailChannels account.

IMPORTANT

Sub-accounts are only available to parent accounts on 100K and higher plans.

Create method ​

Creates a new sub-account under the parent account.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.create('My Company', 'validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.subAccounts.create('My Company', 'validhandle123')

Params ​

  • companyName string required: The name of the company associated with the sub-account.

    TIP

    This name is used for display purposes only and does not affect the functionality of the sub-account. The length must be between 3 and 128 characters.

  • handle string optional: The handle of the sub-account to create.

    TIP

    The length must be between 3 and 128 characters, and it may contain only lowercase letters and numbers.

    If no handle is provided, a random handle will be generated.

Response ​

  • data SubAccountsAccount | null nullable
    • companyName string guaranteed: The name of the company associated with the sub-account.
    • enabled boolean guaranteed: If the sub-account is enabled.
    • handle string guaranteed: The handle for the sub-account.
  • error string | null nullable

List method ​

Retrieves all sub-accounts associated with the parent account.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.list()
ts
import { MailChannels } from 'mailchannels-sdk'

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

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

Params ​

  • options SubAccountsListOptions optional: List sub-accounts options.
    • limit number optional: The number of sub-accounts to return. Possible values are 1 to 1000.
    • offset number optional: The offset number to start returning sub-accounts from.

    TIP

    If no options are provided, the default limit is 1000 and the offset is 0.

Response ​

  • data SubAccountsAccount[] | null nullable
    • companyName string guaranteed: The name of the company associated with the sub-account.
    • enabled boolean guaranteed: If the sub-account is enabled.
    • handle string guaranteed: The handle for the sub-account.
  • error string | null nullable

Delete method ​

Deletes the sub-account identified by its handle.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { success, error } = await subAccounts.delete('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.subAccounts.delete('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to be deleted.

Response ​

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

Suspend method ​

Suspends the sub-account identified by its handle. This action disables the account, preventing it from sending any emails until it is reactivated.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { success, error } = await subAccounts.suspend('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.subAccounts.suspend('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to be suspended.

Response ​

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

Activate method ​

Activates a suspended sub-account identified by its handle, restoring its ability to send emails.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { success, error } = await subAccounts.activate('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.subAccounts.activate('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to be activated.

Response ​

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

Create API Key method ​

Creates a new API key for the specified sub-account.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.createApiKey('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.subAccounts.createApiKey('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to create API key for.

Response ​

  • data SubAccountsApiKey | null nullable
    • id number guaranteed: The API key ID for the sub-account.
    • value string guaranteed: API key for the sub-account.
  • error string | null nullable

List API Keys method ​

Retrieves details of all API keys associated with the specified sub-account. For security reasons, the full API key is not returned; only the key ID and a partially redacted version are provided.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.listApiKeys('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.subAccounts.listApiKeys('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to retrieve the API keys for.
  • options SubAccountsListApiKeyOptions optional: List API keys options.
    • limit number optional: The maximum number of API keys included in the response. Possible values are 1 to 1000.
    • offset number optional: Offset into the list of API keys to return.

    TIP

    If no options are provided, the default limit is 100 and the offset is 0.

Response ​

  • data SubAccountsApiKey[] | null nullable
    • id number guaranteed: The API key ID for the sub-account.
    • value string guaranteed: API key for the sub-account.
  • error string | null nullable

Delete API Key method ​

Deletes the API key identified by its ID for the specified sub-account.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { success, error } = await subAccounts.deleteApiKey('validhandle123', 1)
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.subAccounts.deleteApiKey('validhandle123', 1)

Params ​

  • handle string required: The handle of the sub-account for which the API key should be deleted.
  • id number required: The ID of the API key to delete.

Response ​

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

Create SMTP Password method ​

Creates a new API key for the specified sub-account.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.createSmtpPassword('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.subAccounts.createSmtpPassword('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to create SMTP password for.

Response ​

  • data SubAccountsSmtpPassword | null nullable
    • enabled boolean guaranteed: Whether the SMTP password is enabled.
    • id number guaranteed: The SMTP password ID for the sub-account.
    • value string guaranteed: SMTP password for the sub-account.
  • error string | null nullable

List SMTP Passwords method ​

Retrieves details of all API keys associated with the specified sub-account. For security reasons, the full API key is not returned; only the key ID and a partially redacted version are provided.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.listSmtpPasswords('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.subAccounts.listSmtpPasswords('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to retrieve the SMTP passwords for.

Response ​

  • data SubAccountsSmtpPassword[] | null nullable
    • enabled boolean guaranteed: Whether the SMTP password is enabled.
    • id number guaranteed: The SMTP password ID for the sub-account.
    • value string guaranteed: SMTP password for the sub-account.
  • error string | null nullable

Delete SMTP Password method ​

Deletes the SMTP password identified by its ID for the specified sub-account.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { success, error } = await subAccounts.deleteSmtpPassword('validhandle123', 1)
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.subAccounts.deleteSmtpPassword('validhandle123', 1)

Params ​

  • handle string required: The handle of the sub-account for which the SMTP password should be deleted.
  • id number required: The ID of the SMTP password to delete.

Response ​

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

Get Limit method ​

Retrieves the limit of a specified sub-account.

TIP

A value of -1 indicates that the sub-account inherits the parent account's limit, allowing the sub-account to utilize any remaining capacity within the parent account's allocation.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.getLimit('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.subAccounts.getLimit('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to retrieve the limit for.

Response ​

  • data SubAccountsLimit | null nullable
    • sends number guaranteed
  • error string | null nullable

Set Limit method ​

Sets the limit for the specified sub-account.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { success, error } = await subAccounts.setLimit('validhandle123', { sends: 1000 })
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.subAccounts.setLimit('validhandle123', { sends: 1000 })

Params ​

  • handle string required: The handle of the sub-account to set the limit for.
  • limits object required: The limits to set for the sub-account.
    • sends number required

    TIP

    The minimum allowed sends is 0.

Response ​

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

Delete Limit method ​

Deletes the limit for the specified sub-account. After a successful deletion, the specified sub-account will be limited to the parent account's limit.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { success, error } = await subAccounts.deleteLimit('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { success, error } = await mailchannels.subAccounts.deleteLimit('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to delete the limit for.

Response ​

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

Get Usage method ​

Retrieves usage statistics for the specified sub-account during the current billing period.

Usage ​

ts
import { MailChannelsClient, SubAccounts } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const subAccounts = new SubAccounts(mailchannels)

const { data, error } = await subAccounts.getUsage('validhandle123')
ts
import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.subAccounts.getUsage('validhandle123')

Params ​

  • handle string required: The handle of the sub-account to query usage stats for.

Response ​

  • data SubAccountsUsage | null nullable
    • endDate string optional: The end date of the current billing period (ISO 8601 format).
    • startDate string optional: The start date of the current billing period (ISO 8601 format).
    • total number guaranteed: The total usage for the current billing period.
  • error string | null nullable

Type declarations ​

ts
class SubAccounts {
  constructor (protected mailchannels: MailChannelsClient);
  async create (companyName: string, handle?: string): Promise<SubAccountsCreateResponse>;
  async list (options?: SubAccountsListOptions): Promise<SubAccountsListResponse>;
  async delete (handle: string): Promise<SuccessResponse>;
  async suspend (handle: string): Promise<SuccessResponse>;
  async activate (handle: string): Promise<SuccessResponse>;
  async createApiKey (handle: string): Promise<SubAccountsCreateApiKeyResponse>;
  async listApiKeys (handle: string, options?: SubAccountsListApiKeyOptions): Promise<SubAccountsListApiKeyResponse>;
  async deleteApiKey (handle: string, id: number): Promise<SuccessResponse>;
  async createSmtpPassword (handle: string): Promise<SubAccountsCreateSmtpPasswordResponse>;
  async listSmtpPasswords (handle: string): Promise<SubAccountsListSmtpPasswordResponse>;
  async deleteSmtpPassword (handle: string, id: number): Promise<SuccessResponse>;
  async getLimit (handle: string): Promise<SubAccountsLimitResponse>;
  async setLimit (handle: string, limit: SubAccountsLimit): Promise<SuccessResponse>;
  async deleteLimit (handle: string): Promise<SuccessResponse>;
  async getUsage (handle: string): Promise<SubAccountsUsageResponse>;
}
All type declarations

Responses

ts
interface DataResponse<T> {
  data: T | null;
  error: string | null;
}
ts
interface SuccessResponse {
  success: boolean;
  error: string | null;
}

Account type declarations

ts
interface SubAccountsAccount {
  companyName: string;
  enabled: boolean;
  handle: string;
}
ts
type SubAccountsCreateResponse = DataResponse<SubAccountsAccount>;
ts
interface SubAccountsListOptions {
  limit?: number;
  offset?: number;
}
ts
type SubAccountsListResponse = DataResponse<SubAccountsAccount[]>;

API Key type declarations

ts
interface SubAccountsApiKey {
  id: number;
  value: string;
}
ts
type SubAccountsCreateApiKeyResponse = DataResponse<SubAccountsApiKey>;
ts
type SubAccountsListApiKeyResponse = DataResponse<SubAccountsApiKey[]>;

SMTP Password type declarations

ts
interface SubAccountsSmtpPassword {
  enabled: boolean;
  id: number;
  value: string;
}
ts
type SubAccountsCreateSmtpPasswordResponse = DataResponse<SubAccountsSmtpPassword>;
ts
type SubAccountsListSmtpPasswordResponse = DataResponse<SubAccountsSmtpPassword[]>;

Limit type declaration

ts
interface SubAccountsLimit {
  sends: number;
}
ts
type SubAccountsLimitResponse = DataResponse<SubAccountsLimit>;

Usage type declarations

ts
interface SubAccountsUsage {
  endDate?: string;
  startDate?: string;
  total: number;
}
ts
type SubAccountsUsageResponse = DataResponse<SubAccountsUsage>;

Source ​

Source • Playground • Docs

Released under the MIT License.

Library created by Yizack