Attachments — Finally Here!

I can’t say how excited I am to announce this one! I can’t count the times we’ve had to respond “No we don’t support attachments yet” to your questions in forum posts and support tickets. Finally, no more of that.

The developers among you might be wondering how to get binary attachment data in our JSON-based REST API. We scratched our heads for some time too, and decided it would be easiest to just use a base64-encoded string. Base64 sure adds some complexity but it makes data so much more resilient to encoding problems that I think it is well worth the effort. With SMTP it is a lot easier since we’ll just parse the MIME parts, collect the attachments and send them along. Okay, parsing those was a bit tricky, but we did it. Case closed.

Has the API changed in some way for email without attachments? #

No, it is fully backwards compatible. We just added a new Attachments array property on the incoming request object that can contain one or more attachments. Here’s an example:

{
  "From" : "sender@example.com",
  "To" : "receiver@example.com",
  "Subject" : "Test",
  "HtmlBody" : "<b>Hello</b>",
  "TextBody" : "Hello",
  "Headers" :  [{ "Name" : "CUSTOM-HEADER", "Value" : "value" }]
  "Attachments": [
    {
      "Name": "readme.txt",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "text/plain"
    },
    {
      "Name": "report.pdf",
      "Content": "dGVzdCBjb250ZW50",
      "ContentType": "application/octet-stream"
    }
  ]
}

Can I send huge files and viruses? #

We allow that only for Chuck Norris’ account — we can’t stop him anyway! For the rest of you we have set limits on how you use the attachments feature. We reject all attachment files that are not in the allowed white list, and we allow a maximum of 10MB of attachment data. For details, check our documentation.

Library support #

Right now you can send attachments through SMTP and only if you do your own JSON requests. We will be updating the Ruby library in the next couple of days, and I hope the rest of the client libraries will get updated soon too.

A gentle warning — use a background job #

Many apps can get away with sending email as a response to a user action and do that right in the same web request handler. Adding attachments to that email may not work that well though. Message size can and will get bigger and the time to submit it to our server will get longer. That is why we recommend that you send email with attachments from a background job. Your users will love you for that!