activecampaign / postmark.js

Official Node.js library for the Postmark API

Postmark Node.js Library

Send emails with the greatest of ease! Postmark allows you to send your application's emails with high delivery rates, including bounce/spam processing and detailed statistics. In addition, Postmark can parse incoming emails which are forwarded back to your application.

Now your node.js application can send emails through Postmark. As the official Node.js library for Postmark, postmark.js has support for the entire REST API.

Requirements

Minimum supported Node version v14.0.0. If you use older Node versions for which active and security support ended , you will need to use older library versions (3.x.x).

Usage

Please see the wiki for quick start tutorial and detailed instructions about sending email at our documentation page. For details about Postmark API in general, please check out Postmark developer docs.

Installation

Installing postmark javascript library is super simple. Use the following command in your terminal:

npm install postmark

Migrating from older versions of the library

Please see wiki for more details.

Issues & Comments

Feel free to contact us if you encounter any issues with the library or Postmark API. Please leave all comments, bugs, requests and issues on the Issues page.

License

The Postmark JavaScript Library is licensed under the MIT license. Please refer to the LICENSE for more information.

postmark.js's Issues

Documentation for creating webhooks is missing `MessageStream`

serverClient.createWebhook allows you to pass a MessageStream key in the object, in addition to Url and Triggers. However, the documentation and the wiki don't specify this.

npm request deprecated

request has been deprecated, see request/request#3142

Please update dependencies.

Thanks.

TemplatedMessage type does not allow Metadata

There is no Metadata field in TemplatedMessage type.

[documentation-wiki] What is the difference between using tags, metadata and custom headers?

I want to send a reply to a previously received message with some kind of code that I can track in the next time I receive a message from this thread.

I was thinking about changing the message header and was looking for how to do it in the documentation.

Then I saw you have tags, metadata and custom headers and I am wondering what are the differences, the pros and cons of each option?

Consistent errors

It would be nice to have more consistent errors from the client.
At the moment an error could be an Error object or it could be just a simple object with { status, message, code }.

This makes it difficult to work with the errors the client returns. If you want errors with a status code maybe you should have a look at Boom, the objects Boom returns are proper errors but also preserve the HTTP information.

Uncaught TypeError: exec is not a function

I'm requiring this package and bundling the scripts together with browserify. When I require('postmark'), I'm seeing this error in the console

Uncaught TypeError: exec is not a function

pointing to the following function:

function _command(cmd, cb) {
  exec(cmd, function(err, stdout, stderr) { // this line reports the error
    cb(stdout.split('\n').join(''))
  }
  )

Any ideas?

Domain verification issues

Hi,

I'm integrating Postmark into our Pulumi infrastructure scripts. As part of that I wish to verify the domains' DKIM and ReturnPath setup but have come across a couple of issues relating to the return values:

client.verifyDomainReturnPath:

• Even if the UI shows return path has validated ReturnPathDomainVerified is false
• Once validated the API returns SPFVerified as true. The response has incorrect casing of SpfVerified though, which is undefined. I work around using (response as any).SPFVerified in TypeScript

client.verifyDomainDKIM:

• The DKIMVerified field is never true, even if DKIMUpdateStatus is equal to Verified

I've worked around these issues, but likely to catch others out. I'm using v2.5.3

Problems Sending Batch Emails & Parsing API Error.

I was trying to send emails using ServerClient.sendEmailBatch. I had some batches failing and giving me an error like this:

{
  message: "PostmarkError",
  code: 0,
  statusCode: 0
}

I modified the installed Postmark NPM module to log out the error earlier and it spewed back a lot of base64 encoded attachment data.

So my problem is twofold:

1. The NPM module doesn't seem to be parsing API errors properly.
2. I think I am sending batches that are exceeding some kind of byte size constraint. I have attachments on each of the messages and they're duplicate attachments.
   2a. Is there a better way to deal with the attachments?
   2b. Is there some kind of byte size limit?

Thank you, will try to provide more information tomorrow.

Sending email after post request gives ETIMEDOUT

Hi there! Any ideas why is this happening? It's not all the time but way too often.

Error:  { PostmarkError: ETIMEDOUT
    at ErrorHandler.module.exports.ErrorHandler.buildError (/var/task/user/index.js:51719:16)
    at ErrorHandler.module.exports.ErrorHandler.generateError (/var/task/user/index.js:51708:25)
    at /var/task/user/index.js:19117:38
    at <anonymous>
    at process._tickDomainCallback (internal/process/next_tick.js:228:7) statusCode: 0, code: 0, name: 'PostmarkError' }

Here's the code I'm using:

const express = require('express');
const port = process.env.PORT || 3000
const app = express();
const bodyParser = require('body-parser');
const postmark = require("postmark");
const client = new postmark.ServerClient(process.env.POSTMARK);
var jsonParser = bodyParser.json()

app.post('/', jsonParser, function (request, response) {
    let submission = request.body.submission;
    console.log("Sending email to " + submission.email);
    client.sendEmailWithTemplate({
        "From": "[email protected]",
        "To": submission.email,
        "TemplateAlias": "contact_form",
        "TemplateModel": {
            "name": submission.name
        }
    })
    .then(res => {
        console.log("Email sent at " + res.SubmittedAt);
    })
    .catch(error => console.log('Error: ', error));
    response.end()
});

app.listen(port, err => {
    if (err) throw err
})

This repository should NOT be a fork - GitHub search does not work on forked repos

If this is the official new repo - you should instead have voodootikigod transfer his repository to you.

Search does not work in GitHub for forked repositories, and it's also really confusing since his repo currently does not have a large "REPOSITORY HAS MOVED" notice at the top of the repo (in description/link).

Not sure why the fork. Please fix.

docs directory is quite big around 30Mb

I had added the postmark dependencies in my project, and I think that this is not relevant to embed the docs directory in the npm package.

Thank you for your understanding.

Add Typescript typings

Keeping the typescript types and the actual code in sync can be difficult, but the power it gives developers for development and safety is huge.

Postmark v2.5.0 & v2.5.1 Has Cryptic XMLHttpRequest Issues

When using postmark.TemplatedMessage and sendEmailBatchWithTemplates I get an odd error without a lot of description. Downgrading to 2.3.5 fixes this issue. The problem is present in both 2.5.0 & 2.5.1.

Message:

PostmarkError: The string did not match the expected pattern.
    at ErrorHandler.Object.<anonymous>.ErrorHandler.buildGeneralError (/Users/zjr/Developer/Current/csns/node_modules/postmark/src/client/ErrorHandler.ts:37:16)
    at ErrorHandler.Object.<anonymous>.ErrorHandler.buildRequestError (/Users/zjr/Developer/Current/csns/node_modules/postmark/src/client/ErrorHandler.ts:23:25)
    at /Users/zjr/Developer/Current/csns/node_modules/postmark/src/client/BaseClient.ts:116:41

Empty cc / bcc arrays

Tried sending an email with the "cc" field set to [] - returns a 403 error (incompatible JSON). Small change but would make the library more robust if it could handle empty arrays in the cc / bcc fields - to handle both scenarios with the same function call

How to migrate from 1.x to 2.x

It might be a lack of my search and reading skills, but I cannot find documentation on how to migrate from 1.x to 2.x. Or are there no breaking changes?

testing API key not enough with sendEmailWithTemplate method

Hi,

I implement test. I use process.env.POSTMARK = "POSTMARK_API_TEST";

in documentation i can read:

it helps ensure that your messages will be accepted by the API

Sadly, if it help to init postmark library without any error, it doesn't allow me to call sendEmailWithTemplate() method. I got the following error:

ApiInputError {
    code: 1101,
    statusCode: 422,
    message: 'The Template\'s \'Alias\' associated with this request is not valid or was not found.',
  }

I used welcome as alias. Any well formed alias should be ok as i am using the test API key.

update readme to mention template API

I was preparing to implement template API support, but it's already in there! I'll update the README to list all the supported API methods.

Sending is not supported on the supplied 'MessageStream'.

Hi there,

Since this morning, I am getting that error :

Sending is not supported on the supplied 'MessageStream'.

But I did not change anything on my server or my code. It happens on some emails that I am forwarding,

What this error means ?

Thanks

2.0.0 types - expose supporting types also

Hi,

we have a service, that enables passing attachments as a parameter and we'd like to use the type from this library, but it seems that Attachment from SupportingTypes.d.ts is not exposed, so we can't declare

import * as postmark from 'postmark'

const userCertificateAttachment: postmark.Models.Attachment = { ... }

Which would make it easier to divide logic. For now we've copied the type, but really would like for it to be visible.

Thank you for the awesome work in 2.0!

Upgrade to axios 0.21.1 to resolve critical security vulnerability

Postmark currently uses [email protected], and it has a critical security vulnerability that only got fixed on [email protected].

warning postmark > [email protected]: Critical security vulnerability fixed in v0.21.1. For more information, see https://github.com/axios/axios/pull/3410

I opened #71 to bump axio's version to the one free of that critical security vulnerability.

2.0.0 Preferred way to refer to types

Hi!

Would you recommend to import types like this:

import * as postmark from 'postmark'
const postmarkClient = new postmark.ServerClient('secretysecret')

or like this?:

import { ServerClient } from 'postmark'
const postmarkClient = new ServerClient('secretysecret')

Note that I can't import

import { MessageSendingResponse } from 'postmark'

But rather I have to

import { Models } from 'postmark'
...
const response: ModelsMessageSendingResponse = ....

Which feels a bit clumsy.

Thank you for the awesome work in 2.0!

Provide a Promise-ified API.

In order to better support async/await support that is coming in newer versions of Node.js, provide a "promisified" implementation client methods. Consider using bluebird to provide this functionality.

Use behind a proxy

What configuration do I need to do for the Postmark npm module work behind a proxy in node.js?

I see that the requestFactory uses the node http and https libraries to make API calls to api.postmarkapp.com, but I do not see any options to provide settings for making calls behind a proxy.

Additionally, I do not see methods to properly make calls behind a proxy...

Child process breaks in electron. And, is bug when installed via npm? `git rev-parse HEAD`

In file lib/postmark/clientDefaults.js

Lines 7-9:

exec('git rev-parse HEAD', { cwd: __dirname }, function (err, stdout, stderr) {
 sha = stdout.split('\n').join('') || 'unknown revision';
});

When installed via npm there is no git repo included and git rev-parse HEAD searches up the tree till it hits one, so this would return the shaw for whatever individual's git repo it was installed in if any.

Either way in Electron, I get a ENOTDIR error:

A JavaScript error occurred in the main process
Uncaught Exception:
Error: spawn ENOTDIR
    at exports._errnoException (util.js:1024:11)
    at ChildProcess.spawn (internal/child_process.js:325:11)
    at exports.spawn (child_process.js:505:9)
    at Object.exports.execFile (child_process.js:220:15)
    at Object.module.(anonymous function) [as execFile] (ELECTRON_ASAR.js:199:20)
    at exports.exec (child_process.js:150:18)
    at childProcess.(anonymous function) (ELECTRON_ASAR.js:687:22)
    at Object.<anonymous> (~/App/Contents/Resources/app.asar/node_modules/postmark/lib/postmark/clientDefaults.js:7:1)
    at Object.<anonymous> (~/App/Contents/Resources/app.asar/node_modules/postmark/lib/postmark/clientDefaults.js:126:3)
    at Module._compile (module.js:569:30)

Cannot set content-type header

I want to be able to send an invite with an email. When you are sending an iCalendar invite the Content-Type header should be text/calendar. I get the error
{ ErrorCode: 300, Message: 'Header \'Content-Type\' not allowed.' }

I do not want to send the invite as an attachment because it will not render the action buttons in most email providers. (However it does show up as a calendar invite as an attachment).

Is there anything to be done?

Warning: a promise was rejected with a non-error: [object Object]

I'm promisifying sendEmailWithTemplate method as advised in this issue comment: #5 (comment).

However postmark library is not sending standard Error objects, which is the usual node convention. Bluebird outputs this warning because it expects all rejections to be rejected with new Error() object.

The code where normal JS object is passed to callback instead of an Error object is here:
https://github.com/wildbit/postmark.js/blob/1e12e27586fd7b3ed863360903be2dd926939891/lib/postmark/clientDefaults.js#L72

Installation fails on node 10.10

system: macOS High Sierra 10.13.6
node version: v10.10.0
yarn version: 1.9.4

When trying to install Postmark in my development environment, the install fails with the following message:

error [email protected]: The engine "node" is incompatible with this module. Expected version ">=4 <=9".

It looks like one of your dependencies needs to be updated in order to support node 10. I'm going to skip integrating Postmark into my app for now, but I may come back to this next week and hit you with a PR if it's as simple as version-bumping one of your deps.

Issue with Bluebird.promisify()

Howdy!

Tried promisifying the sendEmailBatch function and it gave me a peculiar error...

I tried using the callback style and it works, but promises are a must-have in my current project.

Here's the code:

const Promise = require('bluebird');
const postmark = require('postmark');

const client = new postmark.Client(<api_key>);

const messages = []; // array or message objects
const sendEmails = Promise.promisify(client.sendEmailBatch);

return sendEmails(messages);

Unhandled rejection TypeError: this.processRequestWithBody is not a function
at Client.sendEmailBatch (/<project path>/node_modules/postmark/lib/postmark/Client.js:120:14)

Sending a template email with attachment

I'd like to be able to send a templated email with attachment, but can find no documentation on how to do this. I've done plenty of stabbing around and some aborted attempts too. I found the 'emailWithTemplate' method reference in another comment, but that has no attachments method.

Is it possible to help a lost dev out and send me on my way please?

Thanks!

p.s. great product btw despite this little bump in the road here...

Promise is not rejected for batch send email call with errors

Hi, I've got a bit of a problem when using the library to send an email using the sendEmailBatchWithTemplates function.

When sending an invalid batch email the promise still resolves, because the error handler is only checking the status code:

https://github.com/wildbit/postmark.js/blob/cb334f475bb1de76cc51cc68dcad0b67874daaf2/src/client/BaseClient.ts#L162-L164

I've had a chat with the support team, and they said that for all the batch email api calls, the status code will always return 200, so you have to check for an ErrorCode value in the body of the response

I could try and make a PR, but it's probably going to be a breaking change

Add changelog

Hi,

I'm trying to understand what has changed between 1.4.1 and 1.5.0 to assess what I may need to update in my code. Are there any plans to create proper per release changelog?

Thanks for the awseome library!

CORS Error with test code.

I am running the very simple test code. It immediately returns:

Access to fetch at 'https://api.postmarkapp.com//email' from origin 'http://10.1.1.140:3111' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

I can not find anywhere to set the CORS endpoints. Am i missing something simple?

TypeError: Cannot read property 'trim' of undefined

Getting this error when running the server (nodemon server.js)

C:\<USER>\~\server\node_modules\postmark\dist\client\BaseClient.js:22
        this.token = token.trim();
                           ^

TypeError: Cannot read property 'trim' of undefined
    at ServerClient.BaseClient (D:\Manal Files\Office-Work\closebuy\server\node_modules\postmark\dist\client\BaseClient.js:22:28)

version: ^2.6.0

PostmarkError: ETIMEOUT & ServiceUnavailablerError

Hi Postmark!

I've been using the Node Client (v2.2.0) for sometime now and have had zero problems until today. My production server has logged 4 errors in the course of about 30minutes that all originate from Postmark. I am attaching images of all the info I have.

Let me know if you need any more info. Thanks.

Rename getOuboundOverview to getOutboundOverview

Typo in Client.js:

    /**
     * Get overview statistics on Outbound Messages sent from the Server associated with this Client.
     *
     * @memberof Client.prototype
     * @method getOuboundOverview
     * @param {object} [filter] Optional filtering parameters.
     * @param {PostmarkCallback} callback A standard callback that is called when the API request completes.
     * @return {Promise} If no callback is passed, returns a Promise with the JSON response from the API (or error).
     */
    Client.prototype.getOuboundOverview = function(filter, callback) {
        callback = coalesceCallback(filter, callback);
        return this.processRequestWithoutBody('/stats/outbound', 'GET', filter, callback);
    };

How do we create a message stream?

I see the message stream API reference (https://postmarkapp.com/developer/api/message-streams-api#create-a-message-stream), but I'm struggling to figure out how to create it using the SDK. Is this something that has not yet been released?

verifyToken is not a function

Same issue as found in #49

Having the same issue. I'm using the code examples section found on the template I created (i.e. postmark.sendEmailWithTemplate).

root@vps102313:~# node --version
v9.7.1

Ubuntu 16

/root/acorn-autoclaim/node_modules/postmark/dist/client/BaseClient.js:22
this.verifyToken(token);
^

TypeError: this.verifyToken is not a function
at Object.BaseClient (/root/acorn-autoclaim/node_modules/postmark/dist/client/BaseClient.js:22:14)
at Object.ServerClient (/root/acorn-autoclaim/node_modules/postmark/dist/client/ServerClient.js:28:23)
at Object. (/root/acorn-autoclaim/index.js:6:42)
at Module._compile (module.js:662:30)
at Object.Module._extensions..js (module.js:673:10)
at Module.load (module.js:575:32)
at tryModuleLoad (module.js:515:12)
at Function.Module._load (module.js:507:3)
at Function.Module.runMain (module.js:703:10)
at startup (bootstrap_node.js:193:16)

Import with babel returns undefined

When importing postmark with "import" keyword using babel transpiler, the library is undefined.

I created a Gist to reproduce the error : https://gist.github.com/pierreinglebert/0db4fdf08e93b775be12120575f0b3f2

(It worked well with 1.x)

I'm using Node 12.

please ignore

SSL3_GET_RECORD error

Postmark Node.js library on Node v5.12 seems to hit this issue intermittently, it looks like it may be due to that postmark API does not support insecure versions of SSL. The solution to this problem is to enforce TLSv1 on all requests as shown in this comment

> process.versions
{ http_parser: '2.7.0',
  node: '5.12.0',
  v8: '4.6.85.32',
  uv: '1.8.0',
  zlib: '1.2.8',
  ares: '1.10.1-DEV',
  icu: '56.1',
  modules: '47',
  openssl: '1.0.2h' }

Ref:
openssl/openssl#852
nodejs/node#4270 (milestone set to v8)

Error with the Client class.

I'm having an issue with the client library that I didn't have before, my code haven't changed at all and it was working.

Version: 1.6.1
OS: Linux
Node Version: 8.0.0

TypeError: Cannot read property 'processRequestWithBody' of undefined

I can see that the function processRequestWithBody is used by client.sendEmailWithTemplate.

Then again, this was working before, I haven't made any big changes to my code for this to happen. I noticed that before I was using version 1.3.1 (I reinstalled the library because I thought it might be a deprecation or something). Now with the version mentioned above is not working either.

Let me know if you need more details for solving this.

Thanks.

send batch using template

How do I send a batch of emails using a template?

MessageSendingReponse.MessageID should be optional or nullable

Hello,

Shouldn't MessageSendingReponse.MessageID be optional or nullable to handle the case where there's an error with ServerClient.sendEmail?

export interface MessageSendingResponse extends DefaultResponse {
    To?: string;
    Cc?: string;
    Bcc?: string;
    SubmittedAt: string;
    MessageID: string;
}

Node 12 issue

Getting this

TypeError: this.verifyToken is not a function
    at Object.BaseClient (/Sites/domain.tld/tasks/project/node_modules/postmark/dist/client/BaseClient.js:22:14)
    at Object.ServerClient (/Sites/domain.tld/tasks/project/node_modules/postmark/dist/client/ServerClient.js:28:23)
    at Object.module.exports [as func] (/Sites/domain.tld/tasks/project/daily-update.js:8:29)
    at /Sites/domain.tld/index.js:40:24
    at Layer.handle [as handle_request] (/Sites/domain.tld/node_modules/express/lib/router/layer.js:95:5)
    at next (/Sites/domain.tld/node_modules/express/lib/router/route.js:137:13)
    at Route.dispatch (/Sites/domain.tld/node_modules/express/lib/router/route.js:112:3)
    at Layer.handle [as handle_request] (/Sites/domain.tld/node_modules/express/lib/router/layer.js:95:5)
    at /Sites/domain.tld/node_modules/express/lib/router/index.js:281:22
    at param (/Sites/domain.tld/node_modules/express/lib/router/index.js:354:14)

when using the setup guide on https://account.postmarkapp.com/servers/%my id%/get_started like the below, with Node 12.

// Require:
var postmark = require("postmark");

// Send an email:
var client = new postmark.ServerClient("x");

client.sendEmail({
  "From": "[email protected]",
  "To": "x",
  "Subject": "Test",
  "TextBody": "Hello from Postmark!"
});

Issue was temporarily resolved by switching to Node 10 in my project.

Non Typescript documentation

Any chance we can get a documentation without the whole typescript stuff? Lots of devs are not using typescript (for good reasons). Lib documentation is completely useless right now :( That's not even a documentation.

sendEmailBatchWithTemplates not reporting errors

Hello!

I am using the sendEmailBatchWithTemplates method of the ServerClient class and noticed that the returned Promise still resolves successfully even in the case of an error.
To reproduce it, I tried sending an email with a From address which is not in my Sender Signatures. When using the exact same template but with the sendEmailWithTemplate method, I get the following error:
"The 'From' address you supplied ([email protected]) is not a Sender Signature on your account. Please add and confirm this address in order to be able to use it in the 'From' field of your messages.","code":400

However, when using the sendEmailBatchWithTemplates method with the exact same template (wrapped in an array) and From address, the mail never makes it to the Postmark API (it does not show up in my activity log), but the Promise is still resolved successfully, no errors are thrown.

Please look into this issue as methods which fail silently make debugging very difficult.

Thank you!

PostmarkError: Request body larger than maxBodyLength limit

When I try to send a batch of emails with sendEmailBatch() and one of the emails has a large body, then the sending of the whole batch fails and I get this error:

PostmarkError: Request body larger than maxBodyLength limit

This seems to be a known issue, it was discussed on StackOverflow. In my opinion this is a bug and can be fixed by setting maxBodyLength to Infinity. I did a pull request that fixes this problem. Let me know what you think of this.

Are there any downsides of adapting the maxBodyLength to Infinity?

Endpoint for VerifyDKIM and Verify Return Path are missing

Would be nice if both endpoints were available in AdminClient, since the use of SPF is deprecated now.

Do not throw strings or return error callbacks with type object.

Line 23 of Client.js: throw ("You must provide your postmark API key");

Line 73 of ClientDefaults.js: callback({ status: response.statusCode, message: data['Message'], code: data['ErrorCode'] });

In real application frameworks, this makes dealing with your library a huge pita by multiple measures. It's really easy to return an Error instance with custom properties or create your own Error which will be broadly supported by any library working with this dependency.

The primary complaint is about throwing strings. A string is not an error.

Crash when unknown error occurs

When an UnkownError occurs (BaseClient => processHttpRequest => generateError => buildStatusError, default fallback) it looks like the error object hast no body property therefore the following error happens. This leads to the problem that the underlying error is hidden.

TypeError: Cannot read property 'Message' of undefined
--
  | at ErrorHandler.buildStatusError (/app/node_modules/postmark/dist/client/ErrorHandler.js:54:59)
  | at ErrorHandler.generateError (/app/node_modules/postmark/dist/client/ErrorHandler.js:20:25)
  | at /app/node_modules/postmark/dist/client/BaseClient.js:79:38
  | at process._tickCallback (internal/process/next_tick.js:68:7)

I would like to provide a PR but the project is written in Typescript.