Grow with us: Join Postmark's new referral partner program and start earning
Learn more
x
Product news

Getting creative with Postmark’s status API

Shane Rice Shane Rice

We designed our new status page with one big idea: everyone deserves transparency from their Email Service Provider. Our goal is to give our customers info they need to make the best sending decisions for their business or project. So in addition to our new status page, we also launched a status API so our customers can integrate these updates into their workflow to respond to any issues with our performance.

Postmark status API page

Status pages are like icebergs. You see the status updates floating along the top, but it's not always clear how downtime is reported from below the surface. 

We know every application has times when it doesn’t function 100%. Even knowing this, it’s a natural reaction to bristle a little when a system we rely on isn’t available. On the Postmark status page, we count anything we could’ve prevented as downtime. This includes everything from system availability to message delays only affecting Postmark with a specific mailbox provider. We even include maintenance in our incident reports for downtime. The temptation with any status page is to try and spin issues to avoid reporting downtime and give the appearance of a more reliable system. We don’t want to hedge how we report issues to hit specific availability metrics.

Our team works hard to make sure Postmark is reliable and are proud of our track record. Even though we strive for perfection, there are occasional issues. While those issues rarely manifest themselves in lost emails, they can lead to delays. We know transactional email is a critical piece of infrastructure for our customers and that even briefly delayed emails can affect business and increase costs. 

So we want to do more than strive for perfection. We want to enable customers to rapidly and transparently respond to any delivery issues on our end no matter how trivial. With the Postmark status API, customers can integrate our status directly into their processes without having to go and manually check our status page or Twitter when we have an issue. We wanted to talk about a few ways our customers can integrate our status info into their workflow. Whether that means a customer can update an internal dashboard for increased awareness, post a notice to their end users, or even go as far as temporarily switching to a backup service provider, that’s a capability we want to provide.

Getting alerts #

Phone notifications are a key way our team stays on top of alerts, especially when we’re on call. The absolute fastest way to get alerts up and running on your phone from Postmark’s status page is to use a service like Zapier or IFTTT to text you when there's a new RSS entry on our status page.

To start getting SMS updates, you’ll want to grab the Postmark status RSS feed and connect your phone for SMS on your preferred service. Here's an IFTTT recipe we created for you to use.

One disadvantage to using these services is they only check RSS feeds in 5 or 15 minute intervals depending on the service and plan you use. If you want updates on a quicker schedule, you might want to consider polling our API directly on a shorter schedule.

Your Internal dashboards #

Everything we’re sharing on our public status page started as part of an internal dashboard. We understand how important it is to keep track of your systems, and you can integrate Postmark’s status directly into your existing dashboards.

You can use our Status API to incorporate several different data points, but to get started, you can get the current system status with GET /api/1.0/status1. You’ll get a response with UP, MAINTENANCE, DEGRADED, DELAY, DOWN, formatted like this:

{
    "status": "UP", 
    "lastUpdated": "2016-03-17T14:50:24+00:00"
}

Share email delivery data on your status page #

If your customers rely on email from your product that's sent through Postmark, you could incorporate Postmark’s delivery stats into your status page. This would cut down on the places your customers need to check if they encounter an issue. You can use GET /api/1.0/delivery to get delivery data for the last 24 hours, which returns results like this:

[{
    "name": "AOL",
    "dkim": 1,
    "inbox": 1,
    "missing": 0,
    "spam": 0,
    "spf": 1
}, {
    "name": "Apple",
    "dkim": 1,
    "inbox": 1,
    "missing": 0,
    "spam": 0,
    "spf": 1
}, {
    "name": "Gmail",
    "dkim": 1,
    "inbox": 1,
    "missing": 0,
    "spam": 0,
    "spf": 1
}, {
    "name": "Hotmail",
    "dkim": 1,
    "inbox": 1,
    "missing": 0,
    "spam": 0,
    "spf": 1
}, {
    "name": "Yahoo!",
    "dkim": 1,
    "inbox": 1,
    "missing": 0,
    "spam": 0,
    "spf": 1
}]

You can break these stats out by each mailbox provider, or provide an overall delivery rate. DKIM and SPF are included as pass/fail values, while inbox, missing, and spam values are for the percentage each occurred in our delivery testing.

Temporarily failing over #

You might choose to have ESP redundancy built into your product, and the status API can help you keep track of when you need to switch over from Postmark. The first step we’ve already discussed, and that’s polling our API for our current status. Anytime you get a report back with anything besides up, you can pull the incident data into your workflow and make a decision on if you’d like to fail over.

Here’s an example of what an incident response looks like:

{
  "id": "1581",
  "type": "DELAY",
  "created_at": "2016-05-12T16:48:00+00:00",
  "updated_at": "2016-05-12T16:48:00+00:00",
  "title": "Delays and bounces to Microsoft domains",
  "updates": [
    {
      "body": "Messages being sent to Microsoft domains such as hotmail, live, outlook & msn are being delayed or generating soft bounces with the error Transaction Failed. This is not a Postmark specific issue and is coming from Microsoft globally. ",
      "status": "Investigating",
      "timestamp": "2016-05-12T16:48:00+00:00"
    }
  ],
  "resolved_at": null,
  "body": ""
}

In this example, the incident is related to a global issue with a mailbox provider, and you’d probably want to keep sending your transactional email through Postmark. Now you can pull all this data into your ops workflow instead of having to go look it up on Twitter or a status page.

Keeping our customers connected #

Our current status API is the first version of our status notification. We’ve already heard from a few people asking us to integrate this data in Slack, and have even discussed creating a webhook to push status updates out. We’ll keep you updated as we continue to develop our status notification workflow.

We also thought it'd be fun to offer some free credits to anyone who shares a custom integration with their favorite dashboard service (Geckoboard, Statusboard, Librato, etc.) for other Postmark customers to use. If you create one and share it on GitHub, we'll add 50,000 credits to your Postmark account. This offer runs through the end of June, and you can claim your credits by emailing support@postmarkapp.com.

Shane Rice

Shane Rice