Introduction

Zupost is a mail provider that allows you to send emails easily and efficiently. This SDK allows you to integrate Zupost easily into your Node.js applications.

Zupost is a product of The Zu Company.

Integrating this SDK (especially with an AI agent)? Read INTEGRATION.md first. It explains the two operating modes, normal mode (you send from your own domains) and platform mode (you send on behalf of your customers, from their domains), and gives a complete, copy ready recipe for each. The file also ships inside the npm package, at node_modules/zupost/INTEGRATION.md.

Installation

npm install zupost

Usage Examples

Initialize the Client

import { Zupost } from 'zupost';

const zupost = new Zupost('your-api-key');

Send an Email

Zupost is template first: design your emails in the Zupost dashboard and send them by templateId, passing in dynamic variables. This is the recommended approach for almost all use cases — content stays out of your codebase, can be edited without a deploy, and benefits from Zupost's rendering pipeline.

For ad-hoc or dynamically generated content, you can alternatively pass raw html, markdown, or a react component as a fallback.

// Recommended: send with a template
const { id } = await zupost.emails.send({
	from: '[email protected]',
	to: '[email protected]',
	templateId: 'welcome-template',
	variables: { name: 'John' },
});

// Send to multiple recipients with a template
await zupost.emails.send({
	from: '[email protected]',
	to: ['[email protected]', '[email protected]'],
	templateId: 'team-update',
	variables: { teamName: 'Engineering' },
});

Multiple languages

A template holds every language it was translated into, so the same templateId covers all of them — pass locale to pick one. Leave it out for the template's default language.

await zupost.emails.send({
	from: '[email protected]',
	to: '[email protected]',
	templateId: 'welcome-template',
	locale: 'de',
	variables: { name: 'Johann' },
});

locale must be one of the languages the template was actually translated into. An unknown one is rejected with the list of available languages rather than quietly falling back, so a forgotten translation shows up as an error instead of a customer receiving the wrong language.

Fallback: inline content

When a template is not a good fit, you can pass raw content instead. At least one of html, markdown, react, or text is required in that case. html, markdown, and react are mutually exclusive, while text can be sent on its own or added alongside one of them as a plain text alternative.

// Inline HTML
await zupost.emails.send({
	from: '[email protected]',
	to: '[email protected]',
	subject: 'Hello World',
	html: '<h1>Hello!</h1>',
});

// Inline markdown
await zupost.emails.send({
	from: '[email protected]',
	to: '[email protected]',
	subject: 'Team Update',
	markdown: '# Hello Team\n\nThis is a **markdown** email.',
});

// Plain text only
await zupost.emails.send({
	from: '[email protected]',
	to: '[email protected]',
	subject: 'Hello World',
	text: 'Hello! This is a plain text email.',
});

Send with React Email (fallback)

As an alternative to templates, Zupost supports React Email components out of the box.

npm install @react-email/components

import { Zupost } from 'zupost';
import { Html, Head, Body, Container, Text } from '@react-email/components';

const WelcomeEmail = ({ name }: { name: string }) => (
	<Html>
		<Head />
		<Body>
			<Container>
				<Text>Hello {name}!</Text>
				<Text>Welcome to our platform.</Text>
			</Container>
		</Body>
	</Html>
);

const zupost = new Zupost('your-api-key');

await zupost.emails.send({
	from: '[email protected]',
	to: '[email protected]',
	subject: 'Welcome!',
	react: <WelcomeEmail name="John" />,
});

Send a Campaign

const { success, message } = await zupost.campaigns.send({
	campaignId: 'campaign_123',
});

if (success) {
	console.log('Campaign sent:', message);
}

Configuration Options

const zupost = new Zupost('your-api-key', {
	baseUrl: 'https://custom-api.zupost.com', // Optional: custom API URL
});

Contributing

We welcome contributions! Please open an issue or submit a pull request.

License

This SDK is licensed under the MIT License - see the LICENSE file for details.

Zupost is a product of The Zu Company.