mailchannels-sdk 0.7.5 → 0.7.7

package/README.md

@@ -12,10 +12,10 @@ Node.js SDK to integrate [MailChannels API](https://docs.mailchannels.net/) into
 This library provides a simple way to interact with the [MailChannels API](https://docs.mailchannels.net/). It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.
 <!-- #endregion overview -->
 
-<!-- #region note -->
+<!-- #region disclaimer -->
 > [!IMPORTANT]
 > **Disclaimer**: This library is not associated with [MailChannels Corporation](https://mailchannels.com/).
-<!-- #endregion note -->
+<!-- #endregion disclaimer -->
 
 - [✨ Release Notes](CHANGELOG.md)
 - [📖 Documentation](https://mailchannels.yizack.com)
@@ -24,31 +24,43 @@ This library provides a simple way to interact with the [MailChannels API](https
 
 - 🚀 [Features](#features)
 - 📏 [Requirements](#requirements)
-- 🏃 [Quick setup](#quick-setup)
-- 🚧 [Roadmap](#roadmap)
+- 📦 [Installation](#installation)
+- 📚 [Usage](#usage)
+- 📐 [Naming Conventions](#naming-conventions)
 - ⚖️ [License](#license)
 - 💻 [Development](#development)
+- 🧪 [Local simulator](#local-simulator)
 
 ## <a name="features">🚀 Features</a>
 
+<!-- #region features -->
+This SDK fully supports all features and operations available in the [MailChannels API](https://docs.mailchannels.net/). It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.
+
+Some of the things you can do with the SDK:
+
 - Send transactional emails
 - Check DKIM, SPF & Domain Lockdown
 - Configure DKIM keys
 - Webhook notifications
 - Manage sub-accounts
 - Retrieve metrics
+- Inspect webhook delivery batches
 - Handle suppressions
 - Configure inbound domains
 - Manage account and recipient lists
 
+> [!TIP]
+> For a detailed reference mapping each SDK method to its corresponding MailChannels API endpoint reference, see the [SDK-API Mapping](https://mailchannels.yizack.com/sdk-api-mapping)
+<!-- #endregion features -->
+
 ## <a name="requirements">📏 Requirements</a>
 
 - [Create a MailChannels account](https://www.mailchannels.com/pricing/#for_devs)
 - [Create an API key](https://console.mailchannels.net/settings/accountSettings#APIKeys)
 
-## <a name="quick-setup">🏃 Quick setup</a>
+## <a name="installation">📦 Installation</a>
 
-1. Add `mailchannels-sdk` dependency to your project
+Add `mailchannels-sdk` dependency to your project
 
 ```sh
 # npm
@@ -61,92 +73,43 @@ yarn add mailchannels-sdk
 pnpm add mailchannels-sdk
 ```
 
+## <a name="usage">📚 Usage</a>
+
+To authenticate, you'll need an API key. You can create and manage API keys in **Dashboard** > **Account Settings** > **API Keys**.
+
+Pass your API key while initializing a new MailChannels client.
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mailchannels = new MailChannels('your-api-key')
+```
+
+Send an email:
+
+```ts
+const { data, error } = await mailchannels.emails.send({
+  from: 'Name <from@example.com>',
+  to: 'to@example.com',
+  subject: 'Test email',
+  html: '<p>Hello World</p>'
+})
+```
+
+## <a name="naming-conventions">📐 Naming Conventions</a>
+
+<!-- #region naming-conventions -->
+Most properties in the MailChannels API use `snake_case`. To follow JavaScript conventions, the SDK adopts `camelCase` for all properties. This means:
+
+- Most options and responses match the API docs, but field names are `camelCase` rather than `snake_case`.
+- Some fields are grouped into nested objects or renamed for simplicity and better developer experience.
+- While most fields match the API docs (just with `camelCase`), a few may be simplified or reorganized to feel more natural for JavaScript developers.
+<!-- #endregion naming-conventions -->
+
 ## <a name="license">⚖️ License</a>
 
 [MIT License](LICENSE)
 
-<!-- #region roadmap -->
-## <a name="roadmap">🚧 Roadmap</a>
-
-Already implemented features are marked with a checkmark. Please open an issue if you find any bugs or missing features.
-
-> [!NOTE]
-> Links below point to the official MailChannels API documentation, options and responses may differ slightly when using this SDK. Please refer to the [documentation](https://mailchannels.yizack.com) for the correct usage of each feature.
-
-### [Email API](https://docs.mailchannels.net/email-api/api-reference/email-api)
-
-- 📧 Emails
-  - ✅ [Send an Email](https://docs.mailchannels.net/email-api/api-reference/send-an-email)
-  - ✅ [Send an Email Asynchronously](https://docs.mailchannels.net/email-api/api-reference/send-an-email-asynchronously)
-  - ✅ [DKIM, SPF & Domain Lockdown Check](https://docs.mailchannels.net/email-api/api-reference/dkim-spf-domain-lockdown-check)
-  - ✅ [Create DKIM Key Pair](https://docs.mailchannels.net/email-api/api-reference/create-dkim-key-pair)
-  - ✅ [Retrieve DKIM Keys](https://docs.mailchannels.net/email-api/api-reference/retrieve-dkim-keys)
-  - ✅ [Update DKIM Key Status](https://docs.mailchannels.net/email-api/api-reference/update-dkim-key-status)
-  - ✅ [Rotate DKIM Key Pair](https://docs.mailchannels.net/email-api/api-reference/rotate-dkim-key-pair)
-- 📢 Webhooks
-  - ✅ [Enroll for Webhook Notifications](https://docs.mailchannels.net/email-api/api-reference/enroll-for-webhook-notifications)
-  - ✅ [Retrieve Customer Webhooks](https://docs.mailchannels.net/email-api/api-reference/retrieve-customer-webhooks)
-  - ✅ [Delete Customer Webhooks](https://docs.mailchannels.net/email-api/api-reference/delete-customer-webhooks)
-  - ✅ [Retrieve Webhook Signing Key](https://docs.mailchannels.net/email-api/api-reference/retrieve-webhook-signing-key)
-  - ✅ [Validate Enrolled Webhook](https://docs.mailchannels.net/email-api/api-reference/validate-enrolled-webhook)
-- 🪪 Sub-accounts
-  - ✅ [Create Sub-account](https://docs.mailchannels.net/email-api/api-reference/create-sub-account)
-  - ✅ [Retrieve Sub-accounts](https://docs.mailchannels.net/email-api/api-reference/retrieve-sub-accounts)
-  - ✅ [Delete Sub-account](https://docs.mailchannels.net/email-api/api-reference/delete-sub-account)
-  - ✅ [Suspend Sub-account](https://docs.mailchannels.net/email-api/api-reference/suspend-sub-account)
-  - ✅ [Activate Sub-account](https://docs.mailchannels.net/email-api/api-reference/activate-sub-account)
-  - ✅ [Create Sub-account API Key](https://docs.mailchannels.net/email-api/api-reference/create-sub-account-api-key)
-  - ✅ [Delete Sub-account API Key](https://docs.mailchannels.net/email-api/api-reference/delete-sub-account-api-key)
-  - ✅ [Retrieve Sub-account API Keys](https://docs.mailchannels.net/email-api/api-reference/retrieve-sub-account-api-keys)
-  - ✅ [Create Sub-account SMTP Password](https://docs.mailchannels.net/email-api/api-reference/create-sub-account-smtp-password)
-  - ✅ [Delete Sub-account SMTP Password](https://docs.mailchannels.net/email-api/api-reference/delete-sub-account-smtp-password)
-  - ✅ [Retrieve Sub-account SMTP Passwords](https://docs.mailchannels.net/email-api/api-reference/retrieve-sub-account-smtp-passwords)
-  - ✅ [Retrieve Sub-account Limit](https://docs.mailchannels.net/email-api/api-reference/retrieve-sub-account-limit)
-  - ✅ [Set Sub-account Limit](https://docs.mailchannels.net/email-api/api-reference/set-sub-account-limit)
-  - ✅ [Delete Sub-account Limit](https://docs.mailchannels.net/email-api/api-reference/delete-sub-account-limit)
-  - ✅ [Retrieve Sub-account Usage Stats](https://docs.mailchannels.net/email-api/api-reference/retrieve-sub-account-usage-stats)
-- 📊 Metrics
-  - ✅ [Retrieve Engagement Metrics](https://docs.mailchannels.net/email-api/api-reference/retrieve-engagement-metrics)
-  - ✅ [Retrieve Performance Metrics](https://docs.mailchannels.net/email-api/api-reference/retrieve-performance-metrics)
-  - ✅ [Retrieve Recipient Behaviour Metrics](https://docs.mailchannels.net/email-api/api-reference/retrieve-recipient-behaviour-metrics)
-  - ✅ [Retrieve Usage Stats](https://docs.mailchannels.net/email-api/api-reference/retrieve-usage-stats)
-  - ✅ [Retrieve Volume Metrics](https://docs.mailchannels.net/email-api/api-reference/retrieve-volume-metrics)
-  - ✅ [Retrieve Sender Metrics](https://docs.mailchannels.net/email-api/api-reference/retrieve-sender-metrics)
-- 🚫 Suppressions
-  - ✅ [Create Suppression Entries](https://docs.mailchannels.net/email-api/api-reference/create-suppression-entries)
-  - ✅ [Delete Suppression Entry](https://docs.mailchannels.net/email-api/api-reference/delete-suppression-entry)
-  - ✅ [Retrieve Suppression List](https://docs.mailchannels.net/email-api/api-reference/retrieve-suppression-list)
-
-### [Inbound API](https://docs.mailchannels.net/inbound-api/API-reference/inbound-api)
-
-- 🌐 Domains
-  - ✅ [Provision domain](https://docs.mailchannels.net/inbound-api/API-reference/provision-domain)
-  - ✅ [Remove domain](https://docs.mailchannels.net/inbound-api/API-reference/remove-domain)
-  - ✅ [List domains](https://docs.mailchannels.net/inbound-api/API-reference/list-domains)
-  - ✅ [Bulk provision domains](https://docs.mailchannels.net/inbound-api/API-reference/bulk-provision-domains)
-  - ✅ [Add domain list entry](https://docs.mailchannels.net/inbound-api/API-reference/add-domain-list-entry)
-  - ✅ [Get domain list entries](https://docs.mailchannels.net/inbound-api/API-reference/get-domain-list-entries)
-  - ✅ [Delete domain list entry](https://docs.mailchannels.net/inbound-api/API-reference/delete-domain-list-entry)
-  - ✅ [Create login link](https://docs.mailchannels.net/inbound-api/API-reference/create-login-link)
-  - ✅ [Bulk create login links](https://docs.mailchannels.net/inbound-api/API-reference/bulk-create-login-links)
-  - ✅ [Set downstream address](https://docs.mailchannels.net/inbound-api/API-reference/set-downstream-address)
-  - ✅ [Fetch downstream addresses](https://docs.mailchannels.net/inbound-api/API-reference/fetch-downstream-addresses)
-  - ✅ [Update API key](https://docs.mailchannels.net/inbound-api/API-reference/update-api-key)
-- 📋 Lists
-  - ✅ [Add item to customer list](https://docs.mailchannels.net/inbound-api/API-reference/add-item-to-customer-list)
-  - ✅ [Delete item from customer list](https://docs.mailchannels.net/inbound-api/API-reference/delete-item-from-customer-list)
-  - ✅ [Get customer list entries](https://docs.mailchannels.net/inbound-api/API-reference/get-customer-list-entries)
-- 📥 Users
-  - ✅ [Create a recipient](https://docs.mailchannels.net/inbound-api/API-reference/create-a-recipient)
-  - ✅ [Add item to recipient list](https://docs.mailchannels.net/inbound-api/API-reference/add-item-to-recipient-list)
-  - ✅ [Get recipient list entries](https://docs.mailchannels.net/inbound-api/API-reference/get-recipient-list-entries)
-  - ✅ [Delete item from recipient list](https://docs.mailchannels.net/inbound-api/API-reference/delete-item-from-recipient-list)
-- ⚙️ Service
-  - ✅ [Retrieve the condition of the service](https://docs.mailchannels.net/inbound-api/API-reference/retrieve-the-condition-of-the-service)
-  - ✅ [Submit a false negative or false positive report](https://docs.mailchannels.net/inbound-api/API-reference/submit-a-false-negative-or-false-positive-report)
-  - ✅ [Get a list of your subscriptions to MailChannels Inbound](https://docs.mailchannels.net/inbound-api/API-reference/get-a-list-of-your-subscriptions-to-mail-channels-inbound)
-<!-- #endregion roadmap -->
-
 ## <a name="development">💻 Development</a>
 
 <details>
@@ -169,12 +132,72 @@ pnpm test:watch
 # Run typecheck
 pnpm test:types
 
+# Refresh API parity fixtures
+pnpm parity:fixtures
+
+# Run the local Email API simulator
+pnpm simulate:email-api
+
 # Release new version
 pnpm release
 ```
 
 </details>
 
+## <a name="local-simulator">🧪 Local simulator</a>
+
+This repo includes a small local MailChannels Email API simulator at [scripts/email-api-simulator.mjs](./scripts/email-api-simulator.mjs). It keeps state in memory and emulates the SDK-supported Email API endpoints so you can test your application without calling the real MailChannels service.
+
+### Start the simulator
+
+```sh
+# default: http://127.0.0.1:8787
+pnpm simulate:email-api
+```
+
+You can override the bind address with environment variables:
+
+```sh
+MAILCHANNELS_SIMULATOR_HOST=127.0.0.1 MAILCHANNELS_SIMULATOR_PORT=8787 pnpm simulate:email-api
+```
+
+### Point the SDK at the simulator
+
+Use the optional `baseUrl` constructor option when creating the client:
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mailchannels = new MailChannels('local-test-key', {
+  baseUrl: 'http://127.0.0.1:8787'
+})
+
+const { data, error } = await mailchannels.emails.send({
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from the simulator',
+  html: '<p>Local test</p>'
+})
+```
+
+### What the simulator supports today
+
+- Email sends and async sends
+- Domain checks
+- DKIM key create, list, rotate, and update
+- Webhook enrollment, listing, validation, signing key lookup, and batch inspection
+- Sub-account lifecycle, API keys, SMTP passwords, limits, and usage
+- Engagement, performance, recipient behaviour, sender, volume, and usage metrics
+- Suppression create, list, and delete
+
+### Current limitations
+
+- State is in-memory only and is reset when the process stops
+- Any non-empty `X-API-Key` is accepted, with separate in-memory state per API key
+- Webhook responses are simulated locally, but the simulator does not yet emit real webhook callbacks to your application
+
+The next planned expansion is outbound webhook delivery so client applications can test webhook ingestion flows against the simulator as well.
+
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/mailchannels-sdk.svg?style=flat&colorA=070a30&colorB=35a047
 [npm-version-href]: https://npmjs.com/package/mailchannels-sdk