Skip to main content

JavaScript SDK

Table of Contents​

Installation​

npm install @sparrowengg/sparrow-mailer-sdk@0.1.2-stable.0

Configuration​

The SDK requires an API key for authentication. You can initialize the client with the following configuration:

interface SparrowMailConfig {
  basePath?: string; // Optional base URL for the API
  apiKey: string; // Required API key for authentication
}

Main Client Class​

The main client class SparrowMailClient provides access to all SDK functionality:

const client = new SparrowMailClient({
  apiKey: "your-api-key",
  basePath: "https://api.sparrowmailer.com", // optional
});

Email Functions​

sendEmail​

async sendEmail(payload: RequestmodelsEmailPayload)

Sends an email using the provided payload.

Parameters:

  • payload: The email configuration object
    • from: Sender details ({ email: string, name?: string })
    • to: Array of recipients ({ email: string, name?: string }[])
    • subject: Email subject
    • content: Email content ({ type: "text/html" | "text/plain", value: string }[])
    • replyTo (optional): Reply-to email address
    • bcc (optional): Array of BCC recipients
    • headers (optional): Custom headers object
    • attachments (optional): Array of attachments
    • settings (optional): Email settings (tracking, etc.)
    • campaign_id (optional): Campaign identifier

Returns: The response data from the API

getEmailLogs​

async getEmailLogs(options?: {
    email?: string;
    recipientDomain?: string;
    refId?: string;
    startCreatedAt?: string;
    endCreatedAt?: string;
    status?: string;
    subject?: string;
    campaignId?: string;
    recipientType?: string;
    startDeliveredDate?: string;
    endDeliveredDate?: string;
    pageSize?: number;
    pageToken?: string;
  })

Retrieves email logs with optional filtering.

Parameters:

  • options: Optional filtering parameters

Returns: The email logs response

subscribeEmail​

async subscribeEmail(email: string)

Subscribes an email address to EDITH.

Parameters:

  • email: The email address to subscribe

Returns: The subscription success response

unsubscribeEmail​

async unsubscribeEmail(email: string)

Unsubscribes an email address from EDITH.

Parameters:

  • email: The email address to unsubscribe

Returns: The unsubscription success response

Domain Management​

addDomain​

async addDomain(payload: RequestmodelsDomainPayload)

Adds a new domain to your account.

Parameters:

  • payload: The domain configuration object
    • domain: The domain name to add
    • custom_args (optional): Custom arguments object
    • is_tenant_domain (optional): Whether this is a tenant domain
    • is_tenant_subdomain (optional): Whether this is a tenant subdomain
    • shared_with_subaccounts (optional): specific to subaccount sharing
    • ips (optional): Array of IP addresses
    • selector (optional): DKIM selector

Returns: The response data from the API

getDomain​

async getDomain(domain: string)

Retrieves details for a specific domain.

Parameters:

  • domain: The domain name to get details for

Returns: The domain information

verifyDomain​

async verifyDomain(domain: string)

Verifies a domain's ownership and configuration.

Parameters:

  • domain: The domain name to verify

Returns: The verification status

deleteDomain​

async deleteDomain(domain: string)

Removes a domain from your account.

Parameters:

  • domain: The domain name to delete

Returns: The deletion confirmation

Webhook Management​

registerWebhook​

async registerWebhook(payload: RequestmodelsWebhookCreatePayload)

Registers a new webhook endpoint.

Parameters:

  • payload: The webhook configuration object
    • webhook_url: The URL to receive webhook events
    • event: Event type (e.g., 'EMAIL_EVENT', 'DOMAIN_VERIFICATION')
    • method: HTTP method ('POST', 'GET', etc.)
    • headers (optional): Custom headers for the webhook request
    • webhook_options (optional): Additional options

Returns: The webhook registration details

updateWebhook​

async updateWebhook(payload: RequestmodelsWebhookUpdatePayload)

Updates an existing webhook configuration.

Parameters:

  • payload: The webhook update configuration
    • webhook_url (optional): New webhook URL
    • event (optional): New event type
    • method (optional): New HTTP method
    • headers (optional): New headers
    • webhook_options (optional): New options

Returns: The updated webhook details

deleteWebhook​

async deleteWebhook(payload: RequestmodelsWebhookDeletePayload)

Removes a webhook configuration.

Returns: The deletion confirmation

SMTP Configuration​

configureSMTP​

async configureSMTP(payload: RequestmodelsCreateSMTPPayload)

Sets up SMTP configuration.

Parameters:

  • payload: The SMTP configuration object
    • name: Configuration name
    • email: Associated email address
    • config_type: Must be 'smtp'
    • connection_type: 'basic' or 'oauth'
    • config: SMTP details
      • host: SMTP host
      • port: SMTP port
      • username: SMTP username
      • password: SMTP password
      • secure: Security setting ('Auto', 'Tls', 'SSL', 'None')

Returns: The SMTP configuration details

updateSMTP​

async updateSMTP(payload: RequestmodelsUpdateSMTPPayload)

Updates existing SMTP configuration.

Parameters:

  • payload: The SMTP update configuration
    • mailer_id: The mailer ID to update
    • name: New configuration name
    • email: Associated email address
    • config (optional): Updated SMTP details

Returns: The updated SMTP details

getSMTPConfig​

async getSMTPConfig(mailerId: string, options?: RawAxiosRequestConfig)

Retrieves SMTP configuration for a specific mailer.

Parameters:

  • mailerId: The ID of the mailer
  • options: Optional Axios request configuration

Returns: The SMTP configuration

deleteSMTPConfig​

async deleteSMTPConfig(mailerId: string, options?: RawAxiosRequestConfig)

Removes SMTP configuration for a specific mailer.

Parameters:

  • mailerId: The ID of the mailer
  • options: Optional Axios request configuration

Returns: The deletion confirmation

IMAP Configuration​

configureIMAP​

async configureIMAP(payload: RequestmodelsCreateIMAPPayload)

Sets up IMAP configuration.

Parameters:

  • payload: The IMAP configuration object
    • name: Configuration name
    • email: Associated email address
    • config_type: Must be 'imap'
    • connection_type: 'basic' or 'oauth'
    • config: IMAP details
      • host: IMAP host
      • port: IMAP port
      • username: IMAP username
      • password: IMAP password
      • secure: Security setting
    • webhook (optional): Webhook configuration for IMAP events

Returns: The IMAP configuration details

updateIMAP​

async updateIMAP(payload: RequestmodelsUpdateIMAPPayload)

Updates existing IMAP configuration.

Parameters:

  • payload: The IMAP update configuration
    • mailer_id: The mailer ID to update
    • name: New configuration name
    • email: Associated email address
    • config (optional): Updated IMAP details

Returns: The updated IMAP details

getIMAPConfig​

async getIMAPConfig(mailerId: string, options?: RawAxiosRequestConfig)

Retrieves IMAP configuration for a specific mailer.

Parameters:

  • mailerId: The ID of the mailer
  • options: Optional Axios request configuration

Returns: The IMAP configuration

deleteIMAPConfig​

async deleteIMAPConfig(mailerId: string, options?: RawAxiosRequestConfig)

Removes IMAP configuration for a specific mailer.

Parameters:

  • mailerId: The ID of the mailer
  • options: Optional Axios request configuration

Returns: The deletion confirmation

Inbound Email Routing​

configureInboundRouting​

async configureInboundRouting(payload: RequestmodelsIncomingDomainPayload)

Sets up inbound email routing configuration.

Parameters:

  • payload: The inbound routing configuration
    • domain: The domain to configure
    • url: The URL to forward inbound emails to
    • method: HTTP method ('POST', etc.)
    • headers (optional): Custom headers

Returns: The routing configuration details

updateInboundDomain​

async updateInboundDomain(domain: string, payload: RequestmodelsUpdateIncomingDomainPayload)

Updates inbound domain configuration.

Parameters:

  • domain: The domain name to update
  • payload: The new configuration payload

Returns: The updated domain configuration

getInboundDomain​

async getInboundDomain(domain: string)

Retrieves configuration for an inbound domain.

Parameters:

  • domain: The domain name to retrieve

Returns: The domain configuration

createInboundUsername​

async createInboundUsername(payload: RequestmodelsIncomingEmailPayload)

Creates an inbound username configuration.

Returns: The username configuration details

updateInboundUsername​

async updateInboundUsername(
    domain: string,
    username: string,
    payload: RequestmodelsUpdateIncomingEmailPayload
)

Updates an inbound username configuration.

Parameters:

  • domain: The domain name
  • username: The username to update
  • payload: The new configuration payload

Returns: The updated username configuration

getInboundUsername​

async getInboundUsername(domain: string, username: string)

Retrieves configuration for an inbound username.

Parameters:

  • domain: The domain name
  • username: The username to retrieve

Returns: The username configuration

OAuth Management​

setOAuthActive​

async setOAuthActive(payload: RequestmodelsOAuthActiveRequest)

Activate or deactivate OAuth configuration.

Parameters:

  • payload: The activation request
    • mailer_id: The mailer ID
    • active (optional): Active status boolean

Returns: The activation status response

oauthLogin​

async oauthLogin(payload: RequestmodelsOAuthLoginRequest)

Performs OAuth login.

Parameters:

  • payload: The OAuth login request
    • app_id: Application ID
    • redirect_uri (optional): Redirect URI
    • token (optional): Token object
    • mailer_id (optional): Mailer ID
    • type (optional): Login type

Returns: The login success response

Type Definitions​

The SDK exports several type definitions that are used in the function parameters:

export type {
  EmailPayload, // Email sending payload
  DomainPayload, // Domain configuration payload
  WebhookCreatePayload, // Webhook creation payload
  CreateSMTPPayload, // SMTP configuration payload
  CreateIMAPPayload, // IMAP configuration payload
  IncomingDomainPayload, // Inbound domain configuration payload
  SMTPConfig, // SMTP configuration type
  IMAPConfig, // IMAP configuration type
  WebhookConfig, // Webhook configuration type
  EmailRecipient, // Email recipient type
  Content, // Email content type
  Attachment, // Email attachment type
  Settings, // General settings type
};

Example Usage​

import { SparrowMailClient } from "@sparrowengg/sparrow-mailer-sdk";

// Initialize the client
const client = new SparrowMailClient({
  apiKey: "your-api-key",
});

// Send an email
await client.sendEmail({
  to: "recipient@example.com",
  subject: "Test Email",
  content: "Hello, World!",
});

// Add a domain
await client.addDomain({
  domain: "example.com",
});

// Configure webhook
await client.registerWebhook({
  url: "https://your-webhook-url.com",
  events: ["email.sent", "email.delivered"],
});

Features​

  • Send emails with HTML and plain text content
  • Manage email domains
  • Configure SMTP settings
  • Configure IMAP settings
  • Manage webhooks
  • Handle inbound email routing

API Reference​

Email Operations​

  • sendEmail(payload: EmailPayload): Send an email with full configuration options
  • getEmailLogs(options: object): Retrieve email logs with filtering
  • subscribeEmail(email: string): Subscribe an email to lists
  • unsubscribeEmail(email: string): Unsubscribe an email from lists

Domain Operations​

  • addDomain(payload: DomainPayload): Add a new domain
  • getDomain(domain: string): Get domain details
  • verifyDomain(domain: string): Verify a domain
  • deleteDomain(domain: string): Delete a domain

SMTP Operations​

  • configureSMTP(payload: CreateSMTPPayload): Configure SMTP settings
  • updateSMTP(payload: UpdateSMTPPayload): Update SMTP configuration
  • getSMTPConfig(mailerId: string): Get SMTP configuration
  • deleteSMTPConfig(mailerId: string): Delete SMTP configuration

IMAP Operations​

  • configureIMAP(payload: CreateIMAPPayload): Configure IMAP settings
  • updateIMAP(payload: UpdateIMAPPayload): Update IMAP configuration
  • getIMAPConfig(mailerId: string): Get IMAP configuration
  • deleteIMAPConfig(mailerId: string): Delete IMAP configuration

Webhook Operations​

  • registerWebhook(payload: WebhookCreatePayload): Register a webhook
  • updateWebhook(payload: WebhookUpdatePayload): Update webhook settings
  • deleteWebhook(payload: WebhookDeletePayload): Delete a webhook

Inbound Email Operations​

  • configureInboundRouting(payload: IncomingDomainPayload): Configure inbound email routing
  • updateInboundDomain(domain: string, payload: UpdateIncomingDomainPayload): Update inbound domain configuration
  • getInboundDomain(domain: string): Get inbound domain configuration
  • createInboundUsername(payload: IncomingEmailPayload): Create inbound username
  • updateInboundUsername(domain: string, username: string, payload: UpdateIncomingEmailPayload): Update inbound username
  • getInboundUsername(domain: string, username: string): Get inbound username details

OAuth Operations​

  • setOAuthActive(payload: OAuthActiveRequest): Activate/deactivate OAuth
  • oauthLogin(payload: OAuthLoginRequest): Perform OAuth login

Authentication​

This SDK uses Bearer token authentication. Your API key is automatically included in all API requests as a Bearer token in the Authorization header.