DEV Community: Yizack Rangel

I Built an Open-Source project. It Became the Official MailChannels JS SDK

Yizack Rangel — Thu, 13 Aug 2026 18:08:57 +0000

How an independent open-source project grew into a full TypeScript SDK and was eventually adopted by MailChannels.

Sometimes, open-source projects start with a very small problem.

You build something because you need it yourself, publish it because you think someone else might find it useful, and then keep improving it simply because you enjoy building software.

That was the story behind mailchannels-sdk.

What started as a small Nuxt integration eventually became a full Node.js and TypeScript SDK for MailChannels. Along the way, I learned a lot from the Vue, Nuxt, and UnJS ecosystems, took inspiration from other developer-focused tools such as Resend, and eventually had the opportunity to join MailChannels and get the project adopted and officially maintained.

This is the story of how that happened.

TL;DR

Built a small Nuxt integration that evolved into a full TypeScript SDK for MailChannels.
The SDK focuses on developer experience (camelCase, TypeScript types, local simulator) and covers 40+ endpoints.
I joined MailChannels and now help maintain the SDK; contributions and feedback are welcome.

What you'll learn

Why I built the SDK and the problems it solves
How the project evolved from a Nuxt module into a Node.js SDK
Key design choices and what's next

Discovering MailChannels

I first discovered MailChannels in 2022–2023 while working on several personal and professional projects that needed a simple and affordable way to send emails.

I'm primarily a web application developer, and at the time I was working a lot with Cloudflare Workers. Email was a common requirement: contact forms, welcome emails, registration notifications, and other transactional messages.

MailChannels was a good fit for these projects because it was directly integrated in Cloudflare Workers at no cost, and using it also introduced me to parts of email infrastructure that I hadn't worked with deeply before.

I started learning more about email delivery and security, including things like DKIM signing and domain authentication.

What started as a practical requirement gradually became something I was genuinely interested in.

The Cloudflare Workers problem

I continued using MailChannels across several projects.

Then, in October 2024, MailChannels announced the end of support for Cloudflare Workers.

I had already built several applications around MailChannels, and replacing all of those integrations with another provider wasn't particularly appealing.

Fortunately, MailChannels was offering its Email API with a free tier. I signed up, obtained an API key, and continued using MailChannels through the Email API.

That solved the immediate problem.

But it also exposed another one.

The API was fine. My integrations weren't

The MailChannels API gave me everything I needed, but I found myself repeatedly building the same request structures across different projects.

You need to know how properties such as personalizations work, remember the available options, construct the request correctly, and make sure the payload matches the API specification.

Doing it once is easy.

Doing it across multiple projects gets repetitive.

I started thinking that TypeScript could make this experience much nicer.

Instead of manually constructing API requests every time, I wanted something closer to:

import { MailChannels } from "mailchannels-sdk"

const mailchannels = new MailChannels("your-api-key")

await mailchannels.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Welcome!",
  html: "<p>Thanks for joining</p>"
})

The MailChannels Email API wasn't necessarily the problem.

I wanted a better developer experience around it.

Starting with Nuxt

My first solution wasn't a Node.js SDK.

I mainly use Nuxt in my own web projects, so I initially created a small Nuxt module (nuxt-mailchannels) to make MailChannels easier to integrate into those applications.

That small project solved my immediate problem.

But working within the Nuxt ecosystem also influenced how I thought about the library.

The Vue, Nuxt, and broader UnJS ecosystem has always been a big source of inspiration for me. There is a strong focus on developer experience, TypeScript, clean APIs, composability, portability, and making complicated things feel simple.

Working with projects such as Nuxt, Nitro, and other UnJS packages taught me a lot about how good JavaScript tooling can feel.

I wanted to bring some of those ideas into the MailChannels integration.

Eventually I started asking myself:

Why should this only work for my Nuxt projects?

From a Nuxt module to a Node.js SDK

I had also been looking at other projects in the JavaScript ecosystem and was particularly inspired by how Resend structured its Node.js package.

The API was simple and pleasant to use.

That made me think:

What if MailChannels had something similar?

At that point, the project started becoming more ambitious.

Instead of a small Nuxt module, I decided to build a proper Node.js SDK for MailChannels.

The goal wasn't simply to wrap a few HTTP endpoints.

I wanted to cover the MailChannels API as completely as possible while making the interface feel natural to JavaScript and TypeScript developers.

Today, the SDK covers a broad range of MailChannels Email API functionality, with around +40 official endpoints.

Making an API feel like JavaScript

One of the things I care about most in the SDK is the developer experience.

The MailChannels API uses snake_case for many of its properties. That's perfectly reasonable for an HTTP API, but JavaScript developers generally expect camelCase.

So the SDK intentionally adapts the API to JavaScript conventions.

Instead of:

some_property_name

you generally work with:

somePropertyName

Some properties are also grouped into nested objects or simplified when that makes the API easier to understand.

The goal isn't to reproduce the HTTP API exactly.

The goal is to create an API that feels like a JavaScript library.

Building more than `send()`

The project has grown considerably since those first experiments.

Sending transactional emails is still at the heart of the SDK, but it now covers much more of the MailChannels platform.

Some of the things you can do include:

Send transactional emails
Check DKIM, SPF, and Domain Lockdown
Custom tracking domains
Configure DKIM keys
Manage webhooks
Manage sub-accounts
Retrieve metrics
Inspect webhook delivery batches
Handle suppressions
Run a local simulator for development and testing
Nodemailer transport
CLI commands

The SDK also includes an AI-agent skill containing focused documentation and recipes for coding agents such as Claude Code, Cursor, Codex, and similar tools.

These aren't features I originally planned when I created the first Nuxt module.

They came naturally as the project evolved, joining forces officially with MailChannels, and we started thinking about what would make the SDK genuinely useful to other developers.

I built it because I enjoy open source

There wasn't a business plan behind this project.

I built it because I enjoy coding.

I enjoy publishing things on GitHub, npm, experimenting with ideas, learning from other open-source projects, and seeing something I built become useful outside my own projects.

Even without a direct monetary return, there's a lot of personal satisfaction in that.

You solve a problem for yourself, turn the solution into a reusable project, and eventually someone else can benefit from it.

That's one of the things I love about open source.

When the project became more than my project

One of the most rewarding parts of this journey was seeing the project evolve from something I created independently into something connected to the company whose API it was built for.

What started as my own Nuxt integration eventually became a complete Node.js SDK for MailChannels.

The project is now officially maintained with MailChannels involvement, and I'm the Lead Maintainer of the Node.js SDK at MailChannels.

As the project became an official MailChannels SDK, it was migrated from my personal GitHub repository to the MailChannels organization on Bitbucket.

That transition is something I never really planned when I published the first version.

I was simply trying to make my own projects easier to maintain.

It's a good reminder of one of the things I love about open source: you don't always know where a project is going when you publish the first version.

What's next?

The project is still actively developed.

As the MailChannels Email API evolves, I'll continue keeping the SDK synchronized with it, refining the developer experience, and adding support for new capabilities.

The underlying goal hasn't changed since the beginning:

Make working with MailChannels feel natural for JavaScript and TypeScript developers.

What started as a small Nuxt module for my own projects has grown into a full Node.js SDK.

And for me, that's one of the most rewarding parts of building in open source.

You don't necessarily start by trying to build something important.

Sometimes you just build something you need.

You publish it.

You keep improving it.

And eventually, it can become something meaningful to people beyond yourself.

Try it

If you're building a Node.js or TypeScript application that uses MailChannels, you can install the SDK with:

npm install mailchannels-sdk

The project is open source, actively maintained, and feedback and contributions are welcome.

Official documentation: https://docs.mailchannels.com
Personal documentation: https://mailchannels.yizack.com
NPM: https://www.npmjs.com/package/mailchannels-sdk
Source: https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js
MailChannels: https://www.mailchannels.com/

nuxt-twemoji

Yizack Rangel — Thu, 22 Jun 2023 00:42:17 +0000

Twemoji module for Nuxt. Render emojis as SVG elements or PNG images

Features
Quick Setup
Module configs
Components
Usage (Twemoji)
- Twemoji properties
- Rendering
- Definitions
- More examples
- Twemoji Default CSS
Usage (Twemojify)
- Twemojify properties
- Parser
- Twemojify Default CSS
Usage (TwemojiParse)
- TwemojiParse properties
- DOM parser
- TwemojiParse Default CSS
Credits
Development

Features

Nuxt 4 ready
Emoji 17.0 support
Render emoji by character
Render emoji by codepoint
Render emoji by definition object
SVG rendering by default
SVG caching with localStorage
PNG image render option
Twitter Emoji assets from ex-Twitter author (jdecked/twemoji) fork repository
Assets from the jsDelivr CDN
Multiples ways of use

Quick Setup

Add nuxt-twemoji dependency to your project

npx nuxi@latest module add twemoji

Add nuxt-twemoji to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-twemoji'
  ]
})

That's it! You can now use nuxt-twemoji in your Nuxt app ✨

Module configs

You can configure the module by adding the twemoji property to the nuxt.config.ts file. The following are the default configurations:

export default defineNuxtConfig({
  twemoji: {
    cache: {
      maxAge: 3.154e+7 // SVG cache expiration time in seconds (1 year)
    },
    mode: 'svg' // Default rendering mode. 'svg' or 'png'
  }
})

Components

You can make use of any of these available components according to your Nuxt app needs.

Name	Description	SSR
`Twemoji`	Renders Twemojis by emoji characters, codepoint or definition.	✔️
`Twemojify`	Parses a text and replaces all emoji characters with Twemoji svg elements or png images.	✔️
`TwemojiParse`	Wrap elements with the component and it will parse all emoji characters found with Twemoji svg or png image elements.	❌

Usage (`Twemoji`)

Find emojis from emojipedia, getemoji or unicode emoji list
In your project, use the component <Twemoji emoji="" />, where emoji is the emoji character or codepoint.
If you employ SSR (Server Side Rendering) in your Nuxt application, this module will inject the emoji <svg> or <img> element into the output code during your project's build/generate process. Alternatively, if SSR is not used, the emojis will dynamically render during client runtime.

`Twemoji` properties

Property	Required	Default	Type
`emoji`	Yes		`string` or `EmojiDefinition`
`size`	No	`1em`	`string`
`mode`	No		`svg` \

Rendering

Use the emoji property to render an emoji by character.

<!-- Render SVG element -->
<Twemoji emoji="🚀" />

<!-- Resize -->
<Twemoji emoji="🚀" size="2em" />

<!-- Render PNG <img> element -->
<Twemoji emoji="🚀" mode="png" />

Use the emoji property to render an emoji by codepoint.

<Twemoji emoji="1F60A" />

<Twemoji emoji="U+1F60A" />

Use the emoji property to render an emoji by definition.

<script setup>
import { twSmilingFaceWithSmilingEyes } from 'nuxt-twemoji/emojis'
</script>

<template>
  <Twemoji :emoji="twSmilingFaceWithSmilingEyes" />
</template>

The emojis file has been generated using the self made generateEmojis.js script, which fetches emojis data from the Unicode public Emoji 17.0 file available at https://unicode.org/Public/17.0.0/emoji/emoji-test.txt

Definitions

The EmojiDefinition type represents objects that have these specific three string properties:

code represents the code associated with the emoji.
emoji represents the actual emoji.
name represents the name of the emoji.

type EmojiDefinition = {
  code: string,
  emoji: string,
  name: string
}

More examples

Check out the 🏀 Online playground for more examples.

`Twemoji` Default CSS

Both the <svg> and <img> tags will have the .twemoji class assigned to them. These are the default styles, but you can add your own styles by using the class name.

.twemoji {
  display: inline-block;
  vertical-align: middle;
}

Usage (`Twemojify`)

This component parses a string text and replaces all emoji characters with Twemoji svg elements or png images.

In the project, use the component <Twemojify text="" />, where text is a string.
If you employ SSR (Server Side Rendering) in your Nuxt application, this module will inject the emoji <svg> or <img> element into the output code during your project's build/generate process. Alternatively, if SSR is not used, the emojis will dynamically render during client runtime.

`Twemojify` properties

Property	Required	Type
`text`	Yes	`string`
`mode`	No	`svg` \

Parser

This component uses the @twemoji/parser package by jdecked for identifying emoji entities within a string.

Use the text property to parse all the emoji characters inside a string

<!-- Replaces ❤️ and 🚀 with SVG elements -->
<Twemojify text="I ❤️ Nuxt 🚀" />

<!-- Replaces ❤️ and 🚀 with PNG images -->
<Twemojify text="I ❤️ Nuxt 🚀" mode="png" />

`Twemojify` Default CSS

Both the <svg> and <img> tags will have the .twemojify class assigned to them. These are the default styles, but you can add your own styles by using the class name.

These style rules make sure that parsed emojis will have the same size as the wrapper element.

.twemojify {
  height: 1em;
  width: 1em;
  margin: 0 .05em 0 .1em;
  vertical-align: -0.1em;
}

Usage (`TwemojiParse`)

This component will parse all emoji characters found.

Wrap elements inside the <TwemojiParse> </TwemojiParse> component
If you want to parse emojis with png images, use the mode configuration or property with the component, otherwise it will parse svg images by default.

Note: This component has a drawback as it does not support SSR (Server-Side Rendering) because it is executed during the mounted Vue lifecycle, functioning solely on the client-side.

`TwemojiParse` properties

Property	Required	Type
`mode`	No	`svg` \

DOM parser

This component uses the @twemoji/api package by jdecked and its DOM parser api.

<!-- Replaces 🚀 with SVG image -->
<TwemojiParse>
  <p>Nuxt Twemoji 🚀</p>
</TwemojiParse>

<!-- Replaces 🚀 with PNG image -->
<TwemojiParse mode="png">
  <p>Nuxt Twemoji 🚀</p>
</TwemojiParse>

<!-- You can wrap any amount of emojis inside the component -->
<TwemojiParse>
  <p>Nuxt Twemoji 🚀</p>
  <div>
    <p>I ❤️ Nuxt 🚀</p>
  </div>
</TwemojiParse>

`TwemojiParse` Default CSS

The <img> tags will have the .twemojiParse class assigned to them. These are the default styles, but you can add your own styles by using the class name.

These style rules make sure that parsed emojis will have the same size as the wrapper element.

img.twemojiParse {
  height: 1em;
  width: 1em;
  margin: 0 .05em 0 .1em;
  vertical-align: -0.1em;
}

Credits

Twitter Emoji assets from jdecked/twemoji
Default CDN jsDelivr
Unicode public Emoji 17.0 files
Nuxt, the JavaScript framework for creating SSR Vue applications and its Module Author Guide

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch

# Run typecheck
pnpm test:types

# Release new version
pnpm release

Display a card with your Gists on your GitHub README.md

Yizack Rangel — Fri, 07 Oct 2022 23:56:00 +0000

GitHub Gists Readme (gists-readme)

Display a card with your Gists on your GitHub README.md

Gists List Card
- Example 1
- Example 2
- Example 3
Gist Pin
- Example 1
- Example 2

Generate your card here: https://gists-readme.yizack.com

Gists List Card

Display a list of your gists

Parameters

Parameter	Description	Optional	Default value
`user`	Your GitHub profile username.	No
`theme`	Set the theme of the card.	Yes	`default`
`n`	Number of Gists to display.	Yes	`30`
`title`	Set the title of the card.	Yes	`My Gists`

Card Example 1

Parameter	Value
user	`yizack`
theme	`dark`

Result

[![gists-readme](https://gists-readme.yizack.com/api?user=yizack&theme=dark)](https://gist.github.com/Yizack)

Card Example 2

Parameter	Value
user	`yizack`
n	`2`

Result

[![gists-readme](https://gists-readme.yizack.com/api?user=yizack&n=2)](https://gist.github.com/Yizack)

Card Example 3

Parameter	Value
user	`Cy4Bot`
n	`20`
title	`Cy4Bot Gists`

Result

[![gists-readme](https://gists-readme.yizack.com/api?user=Cy4Bot&n=20&title=Cy4Bot+Gists)](https://gist.github.com/Cy4Bot)

Gists Pin

Parameters

Parameter	Description	Optional	Default value
`user`	Your GitHub profile username.	No
`id`	Your Gist ID	No
`owner`	Shows the owner of the gist,	Yes	`false`
`theme`	Sets the theme of the pin.	Yes	`default`

Pin Example 1

Parameter	Value
user	`yizack`
id	`bbfce31e0217a3689c8d961a356cb10d`

Result

[![gists-readme](https://gists-readme.yizack.com/api/pin?user=yizack&id=bbfce31e0217a3689c8d961a356cb10d)](https://gist.github.com/Yizack/bbfce31e0217a3689c8d961a356cb10d)

Pin Example 2

Parameter	Value
user	`yizack`
id	`8a84dabef525fed523573b47258880e0`
owner	`true`
theme	`dark`

Result

[![gists-readme](https://gists-readme.yizack.com/api/pin?user=yizack&id=8a84dabef525fed523573b47258880e0&owner=true&theme=dark)](https://gist.github.com/Yizack/8a84dabef525fed523573b47258880e0)

Inspired by anuraghazra/github-readme-stats.
Hosted on Vercel with Node.js.

Embeddable Music Player

Yizack Rangel — Wed, 15 Jun 2022 05:49:11 +0000

Embed a simple HTML music player from local audio on your website using MediaElement.js and Color Thief. Inspired by Spotify's embed player.

(Fullscreen Live Demo)

Recommended requeriments

Mp3 audio source.
Square image.

Configuration

Clone or download my repository (Yizack/embeddable-music-player).
Edit the file /player/song.html
- Paste your song name in {SONG-NAME} for the title of your page.
- Paste your audio file URL in {MP3-SOURCE} for the audio that will be played when you press the play button.
- Paste your image URL in {ARTWORK} for the image that will be displayed.
- You can also rename or create a new html file to have different players, for example for the live demo I have /player/just-stay.html.
Color Thief will detect automatically the dominant color of your song image for your player.
Use the code below, replace {YOUR-HTML-PLAYER} with your HTML filename inside the folder /player and paste it on your site where you want your audio player to appear.

  <iframe src="/player/{YOUR-HTML-PLAYER}.html" width="300" height="385"></iframe>

(Example of use on a website using iframes: Dimatis Website)

Thanks to the responsiveness you can play with the width and height as you want.

  <iframe src="/player/{YOUR-HTML-PLAYER}.html" width="100%" height="450"></iframe>

(Another example of use on a website using iframes: Dimatis - Fly Again)

DEV Community: Yizack Rangel

I Built an Open-Source project. It Became the Official MailChannels JS SDK

TL;DR

What you'll learn

Discovering MailChannels

The Cloudflare Workers problem

The API was fine. My integrations weren't

Starting with Nuxt

From a Nuxt module to a Node.js SDK

Making an API feel like JavaScript

Building more than send()

I built it because I enjoy open source

When the project became more than my project

What's next?

Try it

nuxt-twemoji

Table of Contents

Features

Quick Setup

Module configs

Components

Usage (Twemoji)

Twemoji properties

Rendering

Definitions

More examples

Twemoji Default CSS

Usage (Twemojify)

Twemojify properties

Parser

Twemojify Default CSS

Usage (TwemojiParse)

TwemojiParse properties

DOM parser

TwemojiParse Default CSS

Credits

Development

Display a card with your Gists on your GitHub README.md

GitHub Gists Readme (gists-readme)

Gists List Card

Parameters

Card Example 1

Result

Card Example 2

Result

Card Example 3

Result

Gists Pin

Parameters

Pin Example 1

Result

Pin Example 2

Result

Embeddable Music Player

Recommended requeriments

Configuration

Building more than `send()`

Usage (`Twemoji`)

`Twemoji` properties

`Twemoji` Default CSS

Usage (`Twemojify`)

`Twemojify` properties

`Twemojify` Default CSS

Usage (`TwemojiParse`)

`TwemojiParse` properties

`TwemojiParse` Default CSS