@mailchain/mailer-api

Mailer Sending JS

Mailer Sending JS is a JavaScript library for sending emails using Mailchain's mailer service.

Installation

You can install Mailer api using npm or Yarn:

Install

npm install @mailchain/mailer-api @mailchain/sdk

Authentication

To use Mailer you need:

• MAILER_API_KEY - which you need to obtain from Mailchain.
• AUTHOR_PRIVATE_MESSAGING_KEY - export private messaging key follow https://docs.mailchain.com/developer/advanced/private-messaging-key/.
• AUTHOR_ADDRESS - which must match address that corresponds to AUTHOR_PRIVATE_MESSAGING_KEY.

import { privateMessagingKeyFromHex } from '@mailchain/sdk/internal';

if (!process.env.MAILER_API_KEY) {
	throw new Error('missing env variable: MAILER_API_KEY');
}

// export private messaging key follow https://docs.mailchain.com/developer/advanced/private-messaging-key/
if (!process.env.AUTHOR_PRIVATE_MESSAGING_KEY) {
	throw new Error('missing env variable: AUTHOR_PRIVATE_MESSAGING_KEY');
}

// address that relates to the private messaging key
if (!process.env.AUTHOR_ADDRESS) {
	throw new Error('missing env variable: AUTHOR_ADDRESS');
}

const authorPrivateMessagingKey = privateMessagingKeyFromHex(process.env.AUTHOR_PRIVATE_MESSAGING_KEY);

Create content for sending

When you have decided on your Mail content you can create a distribution. The content will be signed with your author private key. Once created the distribution can not be changed.

import { MailerApiFactory, createMailerProof, MailerData } from '@mailchain/mailer-api';

const content = {
    subject: 'My first distribution',
    html: '<p>Hello: this my first distribution</p>',
    plainTextMessage: 'Hello: this my first distribution',
} as MailerData;

const expires = new Date(2024, 1, 1);
const mailerProof = await createMailerProof(
    content,
    process.env.AUTHOR_ADDRESS,
    authorPrivateMessagingKey,
    expires,
);

const mailer = MailerApiFactory(process.env.MAILER_API_KEY);

// create distribution - confirms the author and content
const { data: createdDistribution } = await mailer.postMailerDistributions({
    ...content, // use same content as proof
    fromAddress: process.env.AUTHOR_ADDRESS,
    name: 'first distribution',
    description: 'first distribution - description',
    mailerProof,
});

console.log('created distribution: ', createdDistribution);

Update contacts

Contacts can updated anytime after creating the distribution but before queuing the distribution for sending. This allows you to decided the contacts either in advance or just before sending.

const mailer = MailerApiFactory(process.env.MAILER_API_KEY);
// add contacts - can updated anytime between creating the distribution and sending
await mailer.postMailerDistributionContacts(createdDistribution.id, [
	{
		address: '[e-mail]',
	},
	{
		address: '[e-mail]',
	},
]);

console.log('contacts updated');

Send mail

Once you have added the contacts, a distribution can queued for sending.

const mailer = MailerApiFactory(process.env.MAILER_API_KEY);
// start
await mailer.putMailerDistributionStatusQueue(createdDistribution.id);
console.log('distribution started');