Parrot Messenger is a messaging library that can normalize the APIs for different messaging transports. In its current iteration it supports 3 types of transport classes:
- SMS
- Call
- AWS SES
- Mailchimp (Mandrill)
- Mailgun
- Sendgrid
- SMTP
- Twilio
- Mailjet
- Twilio
Using npm:
$ npm install parrot-messenger
Using bower:
$ bower install parrot-messenger
Using yarn:
$ yarn add parrot-messenger
Parrot needs to be initialized with the transports that it will be using before being used.
// ES6
import Parrot from 'parrot-messenger';
// CommonJS
const { Parrot } = require('parrot-messenger');
const parrot = new Parrot({
transports: [
// List of transports settings enabled
mailgun,
mailchimp,
ses,
sendgrid,
mailjetEmail,
mailjetSMS,
twilioSMS,
twilioCall,
smtp,
],
});
The parrot
instance receives an array of transports with the settings for each transport. Each transport will have slightly different settings, particularly around the authentication for each. Example configurations are available in the examples.js
file.
Each transport has a defaults
object where you can define default parameters for all messages generated by that transport. So for example you can define a default from
value for every message.
This is a sample object for AWS SES transport along with its default values:
const ses = {
name: 'ses',
settings: {
auth: {
region: '',
credentials: {
secretAccessKey: '',
accessKeyId: '',
},
},
defaults: {
from: '[email protected]',
},
},
};
Parrot Messenger works with a simple send
service and a templating, here we'll describe the usage for the send method.
The send method receives 2 parameters, both being objects.
The first parameter is the parameters for the object that we want to send and the second one is the settings for the transport we want to use.
Example API call:
const email = {
to: '[email protected]',
subject: 'Sample Message',
html: 'Hey Joe, nice talking to you!'
};
const transport = {
class: 'email',
name: 'ses'
};
parrot.send(email, transport);
We can also use and register templates when using Parrot Messenger, so we can pre-define a set of messages we will be using. We use a templating language (Handlebars) to replace values inside the template before being sent.
Example Template Registration & Usage
// Register a template, notice the ussage of {{name}}
// this value will be replaced
parrot.templates.register({
name: 'Sample Template',
html: '<p>Hey there {{name}}!!</p>',
});
const messageData = {
to: '[email protected]',
subject: 'Hey there!',
};
const transport = {
class: 'email',
name: 'ses'
};
// Send an email using this template
parrot.templates.send(
'Sample Template',
messageData,
// Sample Data for Template
{ name: 'User' },
// Transport Settings
// Available classes email, sms & call
// Available transports per Class:
// Email: 'ses', 'mailgun', 'mailjetEmail', 'mailchimp', 'smtp'
// SMS: 'twilioSMS', 'mailjetSMS'
// Call: 'twilioCall'
transport
);
If you need to get the HTML template from an API service prior to senting a template you can do this as well. Parrot Messenger will use Axios to make an API request and fetch the necessary data, and it can be mapped from the response.
Example Async Template
// Register template
parrot.templates.register({
name: 'Async Template',
// Request is a standard Axios type object
// with an additional resolve parameter
// that resolves the response of the object
// API reference for Axios:
// https://github.com/axios/axios#axios-api
request: {
method: 'GET',
url: 'https://reqres.in/api/unknown/2',
data: {},
headers: {},
// Path to string we want to use in the request's response
resolve: 'support.text',
},
});
const messageData = {
to: '[email protected]',
subject: 'Hey there!',
};
const transport = {
class: 'email',
name: 'ses'
};
// Send an email using this template
parrot.templates.send(
'Async Template',
messageData,
// Sample Data for Template
{ name: 'User' },
// Transport Settings
transport
);
We are the development partner of choice for several different sized companies who need a team that delivers fast & scalable code understanding users needs and commercial scope.
- Website development
- UX/UI Design
- Webapp Development
- Mobile Development
- Ecommerce
- Specialized enterprise software
- Legacy migrations, debugging and refactors
We don't outsource a single thing. Each wireframe, design and every piece of code is written with outmost care by Blackstone's diverse teams.
- Node.js - Backend
Contributions, issues and feature requests are welcome!
You can also suggest a new feature by creating an Issue. Please wait for confirmation before working on it.
Copyright ยฉ 2020 Blackstone Studio.
This project is MIT licensed.