@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
- How Does It Work
- API
async email(mail: !Mail, data: { html: string, text: string }, config: !Config): void
- Copyright & License
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.
The package is available by importing its default function:
import email from '@artdeco/email'
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 <hello@world.com> . |
to* | string | The TO field, e.g., Foo Bar <foo@bar.co> . |
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 <no-reply@akashic.page>',
to: 'Art Deco <artdecocode@protonmail.com>',
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:<no-reply@akashic.page>
recv protonmail.com >
recv protonmail.com > 250 OK
send protonmail.com > RCPT TO:<artdecocode@protonmail.com>
recv protonmail.com >
recv protonmail.com > 250 Accepted <artdecocode@protonmail.com>
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 <no-reply@akashic.page>
To: Art Deco <artdecocode@protonmail.com>
Date: Tue, 21 Jan 2020 21:03:56 GMT
MIME-Version: 1.0
Message-ID: <45fc1664c17fc9a703e6b5d5302ab5632f4bec7b8cbc384e_1579640636645@akashic.page>
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 >
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 |