send_message

Send a message to one or more recipients, passing content, templates and variables.

Request Fields

These are passed in at the top level of the request.

The arguments section contains the following fields:

Argument Details

• recipients must be supplied in one of the following forms:
  • A comma-separated list of email addresses.
  • An array of email addresses.
  • A key-value structure where the key is the email address and the value is a JSON object containing key-value pairs of variable/value. Note that variable names must be lower-case only.
• headers can contain valid email headers in key/value form where the key represents the specific header (e.g. "from" with no trailing :) and the value is the header’s value. Many headers have specific formatting requirements.
• content can contain definitions for HTML and/or plain-text versions of the email body. These are identified by keys "text/html" and "text/plain" respectively.
• template is a string that describes which project message layout to use. If this is supplied in addition to content then the content will get wrapped in that layout, substituted in place of the nested content tag ({{*}}).
• variables are variables that apply to all recipients of the email. These can be overridden by recipient-specific variables. The key is the variable name and the value is the variable value as substituted in the document. Note that variable names must be lower-case only.
• recipient_override can be specified as a destination for all generated emails. This can be used to test dynamic content without actually delivering the emails to the original recipient.

Request Example

{
  "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 200 OK

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

Error 400 Bad Request

A bad_request error is generated when the API call is incomplete, typically missing fields that are necessary to complete processing.

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

Error 412 Precondition Failed

If an account has been sending, either deliberately or inadvertently, emails with a high level of spam content the API key may be temporarily disabled until this activity is curtailed.

{
  "response" : {
    "status" : "precondition_failed",
    "message" : "The content of your email messages needs to be addressed. Please contact support for further information."
  }
}

Additionally all the common API errors may also be generated.

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_ID",
    "status" : "ok",
    "message" : "This message is an exact duplicate of one previously sent. To deliberately send a duplicate message, add a unique variable to subsequent calls."
  },
  "data": {
    "message": {
      "id": MESSAGE_ID,
      "url": "http://YOUR_ACCOUNT.postageapp.com/projects/YOUR_PROJECT_ID/messages/MESSAGE_ID",
      "duplicate": "ignored"
    }
  }
}

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"
}

Overrride Recipient

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"