@artdeco/email

@artdeco/email Sends e-mails by direct connection to recipient's SMTP server with authorisation and TLS upgrade support to encrypt messages. You can use this for relay services also, such as https://www.smtp2go.com.

yarn add @artdeco/email

Table Of Contents

• Table Of Contents
• How Does It Work
• API
• async email(mail: !Mail, data: { html: string, text: string }, config: !Config): void
  • Mail
  • Config
  • Dkim
• Copyright & License

How Does It Work

You don't need to operate your own SMTP server to send messages: given an email address, you can resolve the MX server of the domain via DNS lookup, and connect to it directly. This package includes an SMTP client that will establish a socket connection, perform TLS upgrade, and authenticate users when necessary (see the bottom of the page for SMTP protocol commands link). After the connection is established, you can just send formatted message.

However, due to spam, most hosting providers such as Azure, etc will block port 25 so you won't be able to do that. That's why there are many online services that allow to send messages via so-called relay services via additional ports like 2525. They usually provide an HTTP API as well, but this package has a standard SMTP client. A relay business-model is to maintain high reputation of their servers so that all messages will be delivered. Although there's only a limited number of free messages that can be sent per month, there's pretty much no alternative nowadays for production transactional emails therefore you just have to go with that.

On the other hand, you might be able to use Gmail's SMTP server if you are a Google Apps customer.

API

The package is available by importing its default function:

import email from '@artdeco/email'

async email(
  mail: !Mail,
  data: { html: string, text: string },
  config: !Config,
): void

Send e-mails by direct connection to recipient's SMTP server. You will most probably want to use a relay SMTP server, as most cloud server providers (Azure, Alibaba) block port 25 for direct connections.

• mail* !Mail: The mail to send.
• data* { html: string, text: string }: The data.
• config* !Config: The config.

Mail: The email object with information about the message.

Name	Type	Description
from*	string	The FROM field, e.g., Hello World <[e-mail]>.
to*	string	The TO field, e.g., Foo Bar <[e-mail]>.
cc	(string | !Array<string>)	Carbon copy the message to these recipients.
bcc	string	Blind carbon copy (without revealing) to these recipients.
subject	string	The email subject.

Config: Options for the program.

Name	Type	Description	Default
dkim	!Dkim	DKIM configuration for signing emails.	-
silent	boolean	Disable printing to console.	false
smtpHost	string	SMTP host to connect to (e.g., an email relay service).	-
smtpPort	string	The port to connect to SMTP server.	-
user	string	The username to use for login.	-
pass	string	The password for login.	-

Dkim: DKIM information for signing messages. If you use a relay, this will not be required.

Name	Type	Description	Default
privateKey*	string	The private key.	-
keySelector	string	The selector.	dkim
domain	string	The domain. This will be deducted from your email host from the mail.to field.	-

When html and text are set, the multipart/alternative MIME type is set on the message that contains both representations. If only text is set, it will be sent without a MIME type. There's no way to currently add attachments.

import email from '@artdeco/email'
import dotEnv from '@demimonde/dotenv'
dotEnv()

export default async () => {
  const mail = await email({
    from: 'Akashic <[e-mail]>',
    to: 'Art Deco <[e-mail]>',
    subject: 'Hello World',
  }, {
    html: 'HTML <span style="color:red">text</span>',
    text: 'text',
  }, {
    smtpHost: 'mail.smtp2go.com',
    smtpPort: 2525,
    user: process.env.SMTP2GO_USER,
    pass: process.env.SMTP2GO_PASSWORD,
  })
  return mail
}

MX connection created:  mail.smtp2go.com
recv protonmail.com > 220 mail.smtp2go.com ESMTP Exim 4.92-S2G Tue, 21 Jan 2020 21:03:56 +0000
send protonmail.com > EHLO akashic.page
recv protonmail.com >
recv protonmail.com > 250-mail.smtp2go.com Hello akashic.page [8.208.77.44]
recv protonmail.com > 250-SIZE 52428800
recv protonmail.com > 250-8BITMIME
recv protonmail.com > 250-DSN
recv protonmail.com > 250-PIPELINING
recv protonmail.com > 250-AUTH CRAM-MD5 PLAIN LOGIN
recv protonmail.com > 250-CHUNKING
recv protonmail.com > 250-STARTTLS
recv protonmail.com > 250-PRDR
recv protonmail.com > 250 HELP
send protonmail.com > STARTTLS
recv protonmail.com >
recv protonmail.com > 220 TLS go ahead
send protonmail.com > EHLO akashic.page
recv protonmail.com >
recv protonmail.com > 250-mail.smtp2go.com Hello akashic.page [8.208.77.44]
recv protonmail.com > 250-SIZE 52428800
recv protonmail.com > 250-8BITMIME
recv protonmail.com > 250-DSN
recv protonmail.com > 250-PIPELINING
recv protonmail.com > 250-AUTH CRAM-MD5 PLAIN LOGIN
recv protonmail.com > 250-CHUNKING
recv protonmail.com > 250-PRDR
recv protonmail.com > 250 HELP
send protonmail.com > MAIL FROM:<[e-mail]>
recv protonmail.com >
recv protonmail.com > 250 OK
send protonmail.com > RCPT TO:<[e-mail]>
recv protonmail.com >
recv protonmail.com > 250 Accepted <[e-mail]>
send protonmail.com > DATA
recv protonmail.com >
recv protonmail.com > 354 Enter message, ending with "." on a line by itself
send protonmail.com > Subject: Hello World
From: Akashic <[e-mail]>
To: Art Deco <[e-mail]>
Date: Tue, 21 Jan 2020 21:03:56 GMT
MIME-Version: 1.0
Message-ID: <[e-mail]>
Content-Type: multipart/alternative; boundary=----e07b67289b0d805a68a96f108df443e8
X-Service: @artdeco/email

------e07b67289b0d805a68a96f108df443e8
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

HTML <span style="color:red">text</span>
------e07b67289b0d805a68a96f108df443e8
Content-Type: text/plain; charset=utf-8

text

------e07b67289b0d805a68a96f108df443e8--
send protonmail.com >
send protonmail.com > .
recv protonmail.com >
recv protonmail.com > 250 OK id=1iu0go-4Xa8vO-Qa
send protonmail.com > QUIT
recv protonmail.com >
recv protonmail.com > 221 mail.smtp2go.com closing connection
recv protonmail.com >

Copyright & License

• SMTP commands reference

GNU Affero General Public License v3.0

Original work on the SMTP client from node-sendmail by GreenPioneer, NGTmeaty and others under MIT license. Email formatting and DKIM support from fannst-nodemailer by Luke Rieff under ISC license.

© Art Deco 2020