Beta Feature Release: Batch API Calls

[Alex Hillman]

Hey Everyone!

Daniel and the team have been hard at work on some big features we'll be testing soon, but I managed to convince him to sneak in one goodie for everyone that made it to production in the last couple of days. Below are his feature release notes - if you see value in supporting batch API calling, we'd encourage you to take it for a spin. 

We'll add this to our public docs soon, but you get the first crack at it. Enjoy!

Description

The email batching feature allows a user to send multiple, individual Postmark mail requests through the API in a single, wrapped call.

Why It Is Needed

You may want to cut down on the time it takes to send batches of email; web requests have overhead, which can artificially throttle sending hundreds or thousands of messages at a time. By allowing you to send up to 500 messages in a single request, those messages skip the web request overhead tax, and are able to get through our queues faster.

How It Works

• Send an HTTP POST to /email/batch

• The HTTP POST body should contain a JSON array containing up to 500 multiple, well-formed Postmark messages:

[
  {
    "From": "sup...@yourapp.com",
    "To": "cust...@yourapp.com",
    "Cc": null,
    "Bcc": null,
    "ReplyTo": null,
    "Subject": "This is a test",
    "HtmlBody": null,
    "TextBody": "This is the first test message",
    "Tag": null,
    "Headers": [],
    "Attachments": []
  },
  {
    "From": "sup...@yourapp.com",
    "To": "cust...@yourapp.com",
    "Cc": null,
    "Bcc": null,
    "ReplyTo": null,
    "Subject": "This is a test",
    "HtmlBody": null,
    "TextBody": "This is the second test message",
    "Tag": null,
    "Headers": [],
    "Attachments": []
  },
]

• The user will receive back a JSON array containing a response for each message in the order they were received
• If the response is too large for the customer's preferences, GZIP support is possible if your client indicates it can accept it via the "Accept-Encoding" header
• If a customer sends 500 messages, but runs out of credits after 300 messages, the last 200 messages get dumped to the user's queue, and the user will receive 300 messages with statuses for those that were successfully sent
• If a customer tries to send too many messages, they will receive HTTP response code 422 (Unprocessable Entity) similar to other user-sourced errors; a new ErrorCode 410 is used to distinguish when the batch size is too large, with a message indicating the problem

Known Limitations

We are currently limited by our configuration-induced 10MB request length limit, so the entire payload still has to respect this limit. A change to our configuration to lift this limit is currently planned. This means that sending batches with attachments is likely not going to be successful for the customer unless batch size and attachment size are on the lower end.

Alex

wildbit.com

[Robert Rawlins]

This sounds great Alex,

The application we currently have in development should have a fairly high load on it so dealing with them in batches certainly sounds like a benefit to us.

I'll look to modify the current spooler we're working on to factoring this new batching stuff and see how we get on.

Thanks,

Robert

[J Lane]

I was under the impression that Postmark was strictly for
transactional e-mails, and shouldn't be used for bulk-mailing
operations. I'm not talking about spamming -- strictly stuff that
you've got permission for, but in the terms of service, under
"Appropriate Email Practices", it says:

Postmark may not be used to send mass emailing campaigns. This
includes, but is not limited to, Marketing Materials, Promotional
Information, Newsletters, etc. You may only send Transactional email
communication.

This new feature seems like it would contradict that. I can't really
think of a "transactional e-mail" that would be from one to many (can
somebody help me out?) I've always been nervous to use Postmark for
sending anything other than one-to-one sign up, or notification-type
messages because of that line in the TOS.

Jon

On Feb 17, 8:18 am, Alex Hillman <dangerouslyawes...@gmail.com> wrote:
> Hey Everyone!
>
> Daniel and the team have been hard at work on some big features we'll be
> testing soon, but I managed to convince him to sneak in one goodie for
> everyone that made it to production in the last couple of days. Below are
> his feature release notes - if you see value in supporting batch API
> calling, we'd encourage you to take it for a spin.
>
> We'll add this to our public docs soon, but you get the first crack at it.
> Enjoy!
>

> *Description*

> The email batching feature allows a user to send multiple, individual
> Postmark mail requests through the API in a single, wrapped call.
>

> *Why It Is Needed*

> You may want to cut down on the time it takes to send batches of email; web
> requests have overhead, which can artificially throttle sending hundreds or
> thousands of messages at a time. By allowing you to send up to 500 messages
> in a single request, those messages skip the web request overhead tax, and
> are able to get through our queues faster.
>

> *How It Works*
>
>    - Send an HTTP POST to /email/batch
>
>    - The HTTP POST body should contain a JSON array containing up to 500
>    multiple, well-formed Postmark messages:
>
> [
>
>
>
>
>
>
>
>
>
> >   {
> >     "From": "supp...@yourapp.com",
> >     "To": "custo...@yourapp.com",

> >     "Cc": null,
> >     "Bcc": null,
> >     "ReplyTo": null,
> >     "Subject": "This is a test",
> >     "HtmlBody": null,
> >     "TextBody": "This is the first test message",
> >     "Tag": null,
> >     "Headers": [],
> >     "Attachments": []
> >   },
> >   {

> >     "From": "supp...@yourapp.com",
> >     "To": "custo...@yourapp.com",

> >     "Cc": null,
> >     "Bcc": null,
> >     "ReplyTo": null,
> >     "Subject": "This is a test",
> >     "HtmlBody": null,
> >     "TextBody": "This is the second test message",
> >     "Tag": null,
> >     "Headers": [],
> >     "Attachments": []
> >   },
> > ]
>

>    - The user will receive back a JSON array containing a response for each

>    message in the order they were received

>    - If the response is too large for the customer's preferences, GZIP

>    support is possible if your client indicates it can accept it via the
>    "Accept-Encoding" header

>    - If a customer sends 500 messages, but runs out of credits after 300

>    messages, the last 200 messages get dumped to the user's queue, and the user
>    will receive 300 messages with statuses for those that were successfully
>    sent

>    - If a customer tries to send too many messages, they will receive HTTP

>    response code 422 (Unprocessable Entity) similar to other user-sourced
>    errors; a new ErrorCode 410 is used to distinguish when the batch size is
>    too large, with a message indicating the problem
>

> *Known Limitations*
> *
> *

> We are currently limited by our configuration-induced 10MB request length
> limit, so the entire payload still has to respect this limit. A change to

> our configuration to lift this limit *is currently planned*. *This means

> that sending batches with attachments is likely not going to be successful
> for the customer unless batch size and attachment size are on the lower end.

> *
>
> Alex
> wildbit.com

[Alex Hillman]

Jon,

You're right about Postmark being strictly for transactional emails. That said, as systems and webapps grow, communication queues and needs can grow with it.

As an example of something that would be perfectly acceptable:

In an issue tracking system, a ticket is assigned to me and 4 other people for observation/response. When changes are made, all 5 of us are meant to get email notifications. Previously, this action would require 5 separate API calls, now it can be done in only 1.

This is fundamentally different because of the PURPOSE of the email, not the volume of the email. Does that make more sense?

Describing transactional email better is something we're working hard on, so it's good to get these questions. If we can clarify further, please let me know!

-Alex

 
/ah
wildbit.com

--
You received this message because you are subscribed to the Google Groups "Postmark API Developers" group.
To post to this group, send email to postmark-ap...@googlegroups.com.
To unsubscribe from this group, send email to postmark-api-deve...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/postmark-api-developers?hl=en.

[Nick Berardi]

Hi Jon,

An out going HTTP call is a very expensive request if you have a very
popular game site that needs to send something like 3 million
transactional emails a day. So if you can batch those emails is
chunks of 10 or 20 that would save on the expensive HTTP call.

Nick

[Nick Berardi]

By the way I exaggerated the numbers just to make a point.

[Alex Hillman]

I was about to ask, if you're sending 3 million emails a day, who are you sending them through?!? ;)

/ah
wildbit.com

[J Lane]

Excellent examples, that helps a lot!



On Feb 17, 12:57 pm, Alex Hillman <dangerouslyawes...@gmail.com>
wrote:

[kool-a]

Hi Alex,

This sounds great and would be very useful. Is there an ETA on general
release? I know its in beta, i am going to take it for a spin but I
will not push it to production unless its out of beta.I think I was
chatting with one of your developers once about templating through the
API and he indicated that this might be in the backlog. For example, I
want to batch 20 emails, right now with this beta release I would need
20 email bodies. With templating i could send one body with merge
fields and 20 records with all these variable fields and then on your
end you just merge these fields in. I think that would really really
really reduce the amount of load by a lot. Postageapp which is a
similar service to yours does this, we did not go with them because
they did not have a bounce feature. I am wondering if this is in the
pipeline.

Thanks

Kunle

On Feb 17, 11:18 am, Alex Hillman <dangerouslyawes...@gmail.com>
wrote:

> Hey Everyone!
>
> Daniel and the team have been hard at work on some big features we'll be
> testing soon, but I managed to convince him to sneak in one goodie for
> everyone that made it to production in the last couple of days. Below are
> his feature release notes - if you see value in supporting batch API
> calling, we'd encourage you to take it for a spin.
>
> We'll add this to our public docs soon, but you get the first crack at it.
> Enjoy!
>

> *Description*

> The email batching feature allows a user to send multiple, individual
> Postmark mail requests through the API in a single, wrapped call.
>

> *Why It Is Needed*

> You may want to cut down on the time it takes to send batches of email; web
> requests have overhead, which can artificially throttle sending hundreds or
> thousands of messages at a time. By allowing you to send up to 500 messages
> in a single request, those messages skip the web request overhead tax, and
> are able to get through our queues faster.
>

> *How It Works*
>
>    - Send an HTTP POST to /email/batch
>
>    - The HTTP POST body should contain a JSON array containing up to 500
>    multiple, well-formed Postmark messages:
>
> [
>
>
>
>
>
>
>
>
>
> >   {
> >     "From": "supp...@yourapp.com",
> >     "To": "custo...@yourapp.com",

> >     "Cc": null,
> >     "Bcc": null,
> >     "ReplyTo": null,
> >     "Subject": "This is a test",
> >     "HtmlBody": null,
> >     "TextBody": "This is the first test message",
> >     "Tag": null,
> >     "Headers": [],
> >     "Attachments": []
> >   },
> >   {

> >     "From": "supp...@yourapp.com",
> >     "To": "custo...@yourapp.com",

> >     "Cc": null,
> >     "Bcc": null,
> >     "ReplyTo": null,
> >     "Subject": "This is a test",
> >     "HtmlBody": null,
> >     "TextBody": "This is the second test message",
> >     "Tag": null,
> >     "Headers": [],
> >     "Attachments": []
> >   },
> > ]
>

>    - The user will receive back a JSON array containing a response for each

>    message in the order they were received

>    - If the response is too large for the customer's preferences, GZIP

>    support is possible if your client indicates it can accept it via the
>    "Accept-Encoding" header

>    - If a customer sends 500 messages, but runs out of credits after 300

>    messages, the last 200 messages get dumped to the user's queue, and the user
>    will receive 300 messages with statuses for those that were successfully
>    sent

>    - If a customer tries to send too many messages, they will receive HTTP

>    response code 422 (Unprocessable Entity) similar to other user-sourced
>    errors; a new ErrorCode 410 is used to distinguish when the batch size is
>    too large, with a message indicating the problem
>

> *Known Limitations*
> *
> *

> We are currently limited by our configuration-induced 10MB request length
> limit, so the entire payload still has to respect this limit. A change to

> our configuration to lift this limit *is currently planned*. *This means

> that sending batches with attachments is likely not going to be successful
> for the customer unless batch size and attachment size are on the lower end.

> *
>
> Alex
> wildbit.com

[Alex Hillman]

Kool-a:

We've marked this new feature as production-ready, we're just waiting on deploying of the documentation - which will look identical to what we've posted here. 

Unfortunately I can't provide news on templating just yet, but we hear you loud and clear.

-Alex

wildbit.com