🪪 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

modular.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')

full.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 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

Retrieves all sub-accounts associated with the parent account.

Usage

modular.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()

full.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 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 the sub-account identified by its handle.

Usage

modular.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')

full.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 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.

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

modular.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')

full.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 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.

Activate method

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

Usage

modular.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')

full.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 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.

Create API Key method

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

Usage

modular.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')

full.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 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 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

modular.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')

full.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 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 API Key method

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

Usage

modular.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)

full.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 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.

Create SMTP Password method

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

Usage

modular.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')

full.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 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 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

modular.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')

full.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 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 SMTP Password method

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

Usage

modular.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)

full.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 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.

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

modular.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')

full.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 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.

Set Limit method

Sets the limit for the specified sub-account.

Usage

modular.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 })

full.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 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 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

modular.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')

full.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 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.

Get Usage method

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

Usage

modular.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')

full.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 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 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

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

Account type declarations

interface SubAccountsAccount {
  companyName: string;
  enabled: boolean;
  handle: string;
}

type SubAccountsCreateResponse = DataResponse<SubAccountsAccount>;

interface SubAccountsListOptions {
  limit?: number;
  offset?: number;
}

type SubAccountsListResponse = DataResponse<SubAccountsAccount[]>;

API Key type declarations

interface SubAccountsApiKey {
  id: number;
  value: string;
}

type SubAccountsCreateApiKeyResponse = DataResponse<SubAccountsApiKey>;

type SubAccountsListApiKeyResponse = DataResponse<SubAccountsApiKey[]>;

SMTP Password type declarations

interface SubAccountsSmtpPassword {
  enabled: boolean;
  id: number;
  value: string;
}

type SubAccountsCreateSmtpPasswordResponse = DataResponse<SubAccountsSmtpPassword>;

type SubAccountsListSmtpPasswordResponse = DataResponse<SubAccountsSmtpPassword[]>;

Limit type declaration

interface SubAccountsLimit {
  sends: number;
}

type SubAccountsLimitResponse = DataResponse<SubAccountsLimit>;

Usage type declarations

interface SubAccountsUsage {
  endDate?: string;
  startDate?: string;
  total: number;
}

type SubAccountsUsageResponse = DataResponse<SubAccountsUsage>;

Source

Source • Playground • Docs