sdx-mailer-sdk

Official Softdirex SDK for integrating with the SDX Mailer API. Provides typed request builders and send methods for all supported email flows: courier messages, customer lifecycle emails, and payment notifications.

Installation

npm install sdx-mailer-sdk

Usage

All flows follow the same two-step pattern:

1. Build the request with a create* function
2. Sign it (set a trx field) and send it with the corresponding send* function

const {
    createCustomerMailerRequest,
    sendMailRegister
} = require('sdx-mailer-sdk');

const request = createCustomerMailerRequest(
    '[email protected]',   // user
    'SecurePass1',        // password
    'MyProduct',          // product
    'verify-token-abc',   // token
    '[email protected]'   // reply_mail
);

request.trx = yourSigningFunction(request); // request must be signed before sending

const result = await sendMailRegister(
    'Basic dXNlcjpwYXNz',       // basicAuth
    'https://mailer.myapp.com', // endpoint
    request
);

API Reference

Courier

Generic emails with an optional call-to-action button.

createCourierRequest(title, subject, message, receiver, reply_mail, btn_label, btn_link)

Builds a CourierRequest payload.

| Parameter | Type | Description | |---|---|---| | title | string | Header title displayed in the email template | | subject | string | Subject line of the email | | message | string | Main body content | | receiver | string | Recipient email address | | reply_mail | string | Reply-to email address | | btn_label | string \| null | Label for the optional action button | | btn_link | string \| null | URL for the optional action button |

Returns: CourierRequest

createCourierExceptionRequest(error, detail, context)

Builds a CourierExceptionRequest payload for error/exception notifications.

| Parameter | Type | Description | |---|---|---| | error | string | Error name or type (e.g. 'HTTP 500') | | detail | string | Detailed error message or stack trace excerpt | | context | string | Context where the error occurred (e.g. service name, endpoint) |

Returns: CourierExceptionRequest

sendCourierMail(basicAuth, endpoint, tokenRQ, productId, isBasic)

Sends a courier email. The tokenRQ must be signed (have a trx field).

| Parameter | Type | Description | |---|---|---| | basicAuth | string \| null | Authorization header (e.g. 'Basic dXNlcjpwYXNz'). Pass null for no auth | | endpoint | string | Base URL of the SDX Mailer API | | tokenRQ | CourierRequest | Signed request payload | | productId | number | Numeric product identifier sent as product-id header | | isBasic | boolean | When true, uses the /basic endpoint variant |

Returns: Promise<any>

sendExceptionMail(basicAuth, endpoint, tokenRQ, productId)

Sends an exception notification email. The tokenRQ must be signed.

| Parameter | Type | Description | |---|---|---| | basicAuth | string \| null | Authorization header. Pass null for no auth | | endpoint | string | Base URL of the SDX Mailer API | | tokenRQ | CourierExceptionRequest | Signed request payload | | productId | number | Numeric product identifier |

Returns: Promise<any>

Customer

Emails for the customer lifecycle: registration and password management.

createCustomerMailerRequest(user, password, product, token, reply_mail)

Builds a CustomerMailerRequest payload used by all customer send* methods.

| Parameter | Type | Description | |---|---|---| | user | string | Username or email address of the customer | | password | string | Customer's password (included in registration emails) | | product | string | Product name shown in the email template | | token | string | Verification or action token (e.g. for password reset links) | | reply_mail | string | Reply-to email address |

Returns: CustomerMailerRequest

sendMailRegister(basicAuth, endpoint, tokenRQ)

Sends a registration welcome email to the customer.

sendMailRegisterByOwner(basicAuth, endpoint, tokenRQ)

Sends a registration email triggered by an owner/admin on behalf of the customer.

sendMailUpdatePassword(basicAuth, endpoint, tokenRQ)

Sends a "please update your password" notification email.

sendMailSuccessUpdatedPassword(basicAuth, endpoint, tokenRQ)

Sends a "password updated successfully" confirmation email.

All four methods share the same signature:

| Parameter | Type | Description | |---|---|---| | basicAuth | string \| null | Authorization header. Pass null for no auth | | endpoint | string | Base URL of the SDX Mailer API | | tokenRQ | CustomerMailerRequest | Signed request payload |

Returns: Promise<any>

Payments

Payment confirmation emails.

createPaymentsMailerRequest(trxId, product)

Builds a PaymentsMailerRequest payload.

| Parameter | Type | Description | |---|---|---| | trxId | string | Transaction ID associated with the payment | | product | string | Product name or licence identifier |

Returns: PaymentsMailerRequest

sendMailPayment(basicAuth, endpoint, tokenRQ)

Sends a payment confirmation email. The tokenRQ must be signed.

| Parameter | Type | Description | |---|---|---| | basicAuth | string \| null | Authorization header. Pass null for no auth | | endpoint | string | Base URL of the SDX Mailer API | | tokenRQ | PaymentsMailerRequest | Signed request payload |

Returns: Promise<any>

Custom Mail

Send a fully custom HTML email with free-form content. Uses API key authentication instead of Basic auth.

createCustomMailRequest(subject, email, content, cc?)

Builds a CustomMailRequest payload.

| Parameter | Type | Description | |---|---|---| | subject | string | Subject line of the email | | email | string | Recipient email address | | content | string | Full HTML content of the email body | | cc | string[] (optional) | List of CC email addresses |

Returns: CustomMailRequest

sendCustomMail(apiKey, endpoint, request)

Sends a custom HTML email. Authenticated via x-api-key header — no trx signing required.

| Parameter | Type | Description | |---|---|---| | apiKey | string | API key in the format sdx_<prefix>.<secret>. Must have can_execute: true | | endpoint | string | Base URL of the SDX Mailer API | | request | CustomMailRequest | Request payload |

Returns: Promise<any>

Example:

const { createCustomMailRequest, sendCustomMail } = require('sdx-mailer-sdk');

const request = createCustomMailRequest(
    'Welcome to our platform',
    '[email protected]',
    '<h1>Hello!</h1><p>Your account is ready.</p>',
    ['[email protected]']
);

const result = await sendCustomMail(
    'sdx_abc123xyz.mysecret',
    'https://mailer.myapp.com',
    request
);

Important notes

• Courier, Customer and Payment send* methods throw a WebServiceException if the request is not signed (missing trx field) or if the API returns an error.
• sendCustomMail does not require a trx field — it uses an API key instead.
• basicAuth must use the format 'Basic <base64(user:password)>' when authentication is required.
• productId is sent as the product-id HTTP header on Courier/Customer/Payment requests.
• API keys must follow the format sdx_<prefix>.<secret> and have at least one permission with can_execute: true.

Publishing

To publish a new version update the version in package.json, then:

npm login
npm publish

Important: Do not include API endpoints, credentials, or internal configuration in the package. The files field in package.json restricts publishing to runtime-only files.