==========
A simple and reliable Node.js mail for sending mail through Amazon SES.
debug module is included if debugging is needed.Start by creating a client object, and then call either the sendEmail or sendRawEmail method
depending on your needs.
var ses = require('node-ses')
, client = ses.createClient({key: 'key', secret: 'secret'});
// Give SES the details and let it construct the message for you.
client.sendEmail({
to: 'aaron.heckmann+github@gmail.com'
, from: 'somewhereOverTheR@inbow.com'
, cc: 'theWickedWitch@nerds.net'
, bcc: ['canAlsoBe@nArray.com', 'forrealz@.org']
, subject: 'greetings'
, message: 'your <b>message</b> goes here'
, altText: 'plain text'
}, function (err, data, res) {
// ...
});
// ... or build a message from scratch yourself and send it.
client.sendRawEmail({
, from: 'somewhereOverTheR@inbow.com'
, rawMessage: rawMessage
}, function (err, data, res) {
// ...
});
npm install node-ses
The module has one primary export:
You'll probably only be using this method. It takes an options object with the following properties:
`key` - your AWS SES key. Defaults to checking `process.env.AWS_ACCESS_KEY_ID` and `process.env.AWS_ACCESS_KEY`
`secret` - your AWS SES secret. Defaults to `process.env.AWS_SECRET_ACCESS_KEY` and `process.env.AWS_SECRET_KEY`
`amazon` - [optional] the amazon end-point uri. defaults to `https://email.us-east-1.amazonaws.com`
Not all AWS regions support SES. Check SES region support to be sure the region you are in is supported.
var ses = require('node-ses')
, client = ses.createClient({ key: 'key', secret: 'secret' });
Composes an email message based on input data, and then immediately queues the message for sending.
There are several important points to know about SendEmail:
sendEmail receives an options object with the following properties:
`from` - email address from which to send (required)
`subject` - string (required). Must be encoded as UTF-8
`message` - can be html (required). Must be encoded as UTF-8.
`altText` - plain text version of message. Must be encoded as UTF-8.
`to` - email address or array of addresses
`cc` - email address or array of addresses
`bcc` - email address or array of addresses
`replyTo` - email address
`configurationSet` - SES configuration set name
`messageTags` - SES message tags: array of name/value objects, e.g. { name: xid, value: 1 }
At least one of to, cc or bcc is required.
Optional properties (overrides the values set in createClient):
`key` - AWS key
`secret` - AWS secret
`amazon` - AWS end point. Defaults to `https://email.us-east-1.amazonaws.com`
The sendEmail method transports your message to the AWS SES service. If AWS
returns an HTTP status code that's less than 200 or greater than or equal to
400, we will callback with an err object that is a direct tranalation of the Error element of the AWS error response.
See Error Handling section below for details on the structure of returned errors.
Check for errors returned since a 400 status is not uncommon.
The data returned in the callback is an object containing the parsed AWS response.
See the SES API Response docs for details.
The res returned by the callback represents the HTTP response to calling the SES REST API as the request module returns it.
The sendEmail method also be provided in all lowercase as sendemail for backwards compatibility.
Sends an email message, with header and content specified by the client. The SendRawEmail action is useful for sending multipart MIME emails. The raw text of the message must comply with Internet email standards; otherwise, the message cannot be sent.
There are several important points to know about SendRawEmail:
sendRawEmail receives an options object with the following properties:
`from` - email address from which to send (required)
`rawMessage` - the raw text of the message which includes a header and a body (required)
Within the raw text of the message, the following must be observed:
rawMessage value must contain a header and a body, separated by a blank line.rawMessage content must be base64-encoded, if MIME requires it.The sendRawEmail method transports your message to the AWS SES service. If Amazon
returns an HTTP status code that's less than 200 or greater than or equal to
400, we will callback with an err object that is a direct translation of the Error element of aws error response.
See Error Handling section below for details on the structure of returned errors.
var CRLF = '\r\n'
, ses = require('node-ses')
, client = ses.createClient({ key: 'key', secret: 'secret' })
, rawMessage = [
'From: "Someone" <someone@example.com>',
'To: "Someone Else" <other@example.com>',
'Subject: greetings',
'Content-Type: multipart/mixed;',
' boundary="_003_97DCB304C5294779BEBCFC8357FCC4D2"',
'MIME-Version: 1.0',
'',
'--_003_97DCB304C5294779BEBCFC8357FCC4D2',
'Content-Type: text/plain; charset="us-ascii"',
'Content-Transfer-Encoding: quoted-printable',
'Hi brozeph,',
'',
'I have attached a code file for you.',
'',
'Cheers.',
'',
'--_003_97DCB304C5294779BEBCFC8357FCC4D2',
'Content-Type: text/plain; name="code.txt"',
'Content-Description: code.txt',
'Content-Disposition: attachment; filename="code.txt"; size=4;',
' creation-date="Mon, 03 Aug 2015 11:39:39 GMT";',
' modification-date="Mon, 03 Aug 2015 11:39:39 GMT"',
'Content-Transfer-Encoding: base64',
'',
'ZWNobyBoZWxsbyB3b3JsZAo=',
'',
'--_003_97DCB304C5294779BEBCFC8357FCC4D2',
''
].join(CRLF);
client.sendRawEmail({
, from: 'someone@example.com'
, rawMessage: rawMessage
}, function (err, data, res) {
// ...
});
Check for errors returned since a 400 status is not uncommon.
The data returned in the callback is an object containing the parsed Amazon json response.
See the SES API Response docs for details.
The res returned by the callback represents the HTTP response to calling the SES REST API as the request module returns it.
The errors returned when sending failed are JavaScript objects that correspond to the Error element as seen in Structure of an Error Response from the official documentation. The properties in error object we return include:
Type element that identifies whether the error was a Receiver, Sender, or NodeSesInternal errorCode element that identifies the type of error that occurredMessage element that describes the error condition in a human-readable formDetail element that might give additional details about the error or might be emptyAn error of Type NodeSesInternal is returned in three cases:
Code will be RequestError and the Message will contain the HTTP request error.Code will be set to XmlError and the Message will contain explanation and the original response.Example error response:
{
"Type": "Sender",
"Code": "ValidationError",
"Message": "Value null at 'message.subject' failed to satisfy constraint: Member must not be null"
}
# Enable in the shell
DEBUG="node-ses" ./server.js
// ... or temporarily set in your code before `node-ses` is required.
process.env.DEBUG='node-ses';
When debugging, it's useful to inspect the raw HTTP request and response send to Amazon. These can then checked against Amazon's documentation for the SendMail API method and the common errors that Amazon might return.
To turn on debugging printed to STDERR, set DEBUG=node-ses in the environment before running your script. You can also set process.env.DEBUG='node-ses'; in your code, before the node-ses module is required.
See the debug module docs for more debug output possibilities.
Unit tests
npm test
To run the full tests, including actually using the AWS SES REST APIs with your credentials, set the following environment variables:
# Your SES Key and secret
NODE_SES_KEY
NODE_SES_SECRET
# An email that is both an verified sende that can also receive test emails. Possibly your own email address
NODE_SES_EMAIL
FAQs
Simple Email Sender for Amazon SES with good docs and error handling
The npm package node-ses receives a total of 10,420 weekly downloads. As such, node-ses popularity was classified as popular.
We found that node-ses demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Maintainers back GitHub’s npm security overhaul but raise concerns about CI/CD workflows, enterprise support, and token management.
Product
Socket Firewall is a free tool that blocks malicious packages at install time, giving developers proactive protection against rising supply chain attacks.
Research
Socket uncovers malicious Rust crates impersonating fast_log to steal Solana and Ethereum wallet keys from source code.