@miso/mail-sdk

SDK for Miso Mail Service - Email and SMTP configuration APIs.

Installation

pnpm add @miso/mail-sdk

Usage

import { createMailClient } from '@miso/mail-sdk';

// Create a client instance
const mailClient = createMailClient({
  endpoint: 'https://mail-service.example.com',
  shopDomain: 'my-shop.myshopify.com',
});

Email APIs

Send Email (User SMTP)

Send email using shop's configured SMTP:

const result = await mailClient.sendEmail({
  to: '[email protected]',
  fromEmail: '[email protected]',
  fromName: 'My Shop', // optional
  replyTo: ['[email protected]'], // optional
  subject: 'Hello!',
  html: '<h1>Welcome!</h1>',
  text: 'Welcome!', // optional
});

console.log(result);
// { success: true, messageId: '...', logId: '...' }

Send Email (System SMTP)

Send email using system SMTP (AWS SES). fromEmail is fixed from server's AWS_SMTP_FROM_EMAIL env:

const result = await mailClient.sendSystemEmail({
  to: '[email protected]',
  fromName: 'Miso Apps', // optional
  replyTo: ['[email protected]'], // optional
  subject: 'Hello!',
  html: '<h1>Welcome!</h1>',
  text: 'Welcome!', // optional
});

Get Email Logs

const logs = await mailClient.getEmailLogs({
  status: 'sent', // optional: 'pending' | 'sent' | 'failed'
  type: 'user', // optional: 'user' | 'system'
  page: 1, // optional
  limit: 20, // optional
});

console.log(logs);
// { logs: [...], total: 100, page: 1, pages: 5 }

SMTP Config APIs

Create/Update SMTP Config

const config = await mailClient.upsertSmtpConfig({
  host: 'smtp.gmail.com',
  port: 587, // optional, default: 587
  secure: false, // optional, default: false
  username: '[email protected]',
  password: 'app-password',
});

Get SMTP Config

const config = await mailClient.getSmtpConfig();
// Returns SmtpConfig or null

Update SMTP Config

const config = await mailClient.updateSmtpConfig({
  port: 465,
  secure: true,
  isActive: true,
});

Delete SMTP Config

const result = await mailClient.deleteSmtpConfig();
// { success: true, message: '...' }

Test SMTP Connection

const result = await mailClient.testSmtpConnection();
// { success: true, message: 'SMTP connection successful' }
// or { success: false, message: '...', error: '...' }

Types

All types are exported from the package:

import type {
  MailClientConfig,
  MailClient,
  // Email types
  SendEmailRequest,
  SendSystemEmailRequest,
  SendEmailResponse,
  EmailLog,
  GetEmailLogsParams,
  GetEmailLogsResponse,
  EmailStatus,
  EmailType,
  // SMTP types
  SmtpConfig,
  CreateSmtpConfigRequest,
  UpdateSmtpConfigRequest,
  TestSmtpResponse,
} from '@miso/mail-sdk';

License

MIT