send_message

URL: https://api.postageapp.com/v.1.0/send_message.json

Request

{ "api_key" : "PROJECT_API_KEY",
  "uid" : "27cf6ede7501a32d54d22abe17e3c154d2cae7f3",
  "arguments" : {

    "recipients" : ["recipient1@example.com", "recipient2@example.com"],

    "headers" : {
      "subject" : "Email Subject",
      "from" : "sender@example.com"
    },

    "content" : {
      "text/plain" : "Text Content",
      "text/html" : "HTML Content"
    },

    "attachments" : {
      "filename.pdf" : {
        "content_type" : "application/octet-stream",
        "content" : "BASE64_ENCODED_CONTENT"
      }
    },

    "template" : "POSTAGEAPP_TEMPLATE",

    "variables" : {
      "global_variable_1" : "value",
      "global_variable_2" : "value"
    }

    "recipient_override" : "me@example.com"

  }
}

Response

successful response:

{ "response" : {
    "uid" : "27cf6ede7501a32d54d22abe17e3c154d2cae7f3",
    "status" : "ok"
  },
  "data" : {
    "message" : {
      "id" : "1234567890"
    }
  }
}

if something was wrong with the message and it was rejected:

{ "response" : {
    "uid" : "27cf6ede7501a32d54d22abe17e3c154d2cae7f3",
    "status" : "bad_request",
    "message" : "Some error message. Like: you forgot the recipients!"
  }
}

UID

Each message in your project has UID associated with it. The purpose is to avoid message duplication. If you do several send_message api calls with the same uid only the first message will be accepted. Messages that follow will be rejected with:

{ "response" : {
    "uid" : "your_duplicate_uid",
    "status" : "bad_request",
    "message" : "Uid your_duplicate_uid already exists. Assuming message duplication."
  }
}

When generating UID, SHA1 hashing arguments + timestamp works great.

UID parameter is optional. If it's not provided with API call, PostageApp will generate one automatically. Please note that messages with same content and addressed to same recipients will generate same hash. So if you want to send identical messages please provide UID.

Arguments

NOTE: Not all of the arguments have to be used in an API call. The most basic of API calls can be made with recipient, headers, and content.

RECIPIENTS

Can be in the following formats starting from a simple string:

"recipients" : "recipient@example.com"

As a comma-separated string. This will ensure that emails with have to header that shows both email addresses:

"recipients" : "recipient_1@example.com, recipient_2@example.com"

As an array. This way recipients only see their own email address:

"recipients" : ["recipient_1@example.com", "recipient_2@example.com"]

As pairs with variables:

"recipients" : {
  "recipient_1@example.com" : {
    "variable_1" : "value",
    "varaible_2" : "value"
  },
  "recipient_2@example.com" : {
    "variable_1" : "value",
    "variable_2" : "value"
  }
}

You can mix and match these formats into something like this (you can't have an array as a hash key though):

"recipients" : {
  "John Doe <recipient_1@example.com>, recipient_2@example.com" : {
    "variable" : "value"
  }
}

HEADERS

Headers can be defined with pairs. At the very least you want to send subject and from:

"headers" : {
  "subject" : "Message Subject",
  "from" : "sender@example.com",
  "reply-to" : "sender@example.com"
}

Note: To send emails in a CC or BCC context, you must add all addresses in the 'recipients' section above. The default behaviour is then BCC, and you can alternatively specify a CC header containing all addresses required as a visible CC. Just adding addresses to a CC header will not send those recipients the message.

CONTENT

Content can be passed for both html and plain text versions:

"content" : {
  "text/html" : "HTML Content",
  "text/plain" : "Plain Text Content"
}

If you want just the html version you can pass it in like this:

"content" : "HTML Content"

ATTACHMENTS

You can send attachments along with the messages:

"attachments" : {
  "example.pdf" : {
    "content_type" : "application/octet-stream",
    "content" : "BASE64_ENCODED_CONTENT"
  },
  "example.zip" : {
    "content_type" : "application/zip",
    "content" : "BASE64_ENCODED_CONTENT"
  }
}

Please note that, depending on the plan, there are restrictions on how big your message can be. It will be rejected if it's over the allowed filesize.

TEMPLATE

Slug of the PostageApp template for your project. content and headers can be completely optional if you have them defined in the template.

"template" : "POSTAGEAPP_TEMPLATE"

VARIABLES

Variables that can be used for content replacement and are not recipient specific (unless there's only one recipient, then it doesn't matter).

"variables" : {
  "global_variable_1" : "value",
  "global_variable_2" : "value"
}

RECIPIENT_OVERRIDE

When developing an application it is often useful to override the list of recipients with your own email. This way you’ll avoid sending emails to real people when you’re developing your app. You can define a single email address:

"recipient_override" : "me@example.com"