Email messages

  • JSON
  • XML

Sending plain text emails

{{codeStart}}

# To send from a User-defined workspace

POST https://api.<region>.whispir.com/workspaces/:workspace_id/messages 

# To send from the default workspace

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

Accept: application/vnd.whispir.message-v1+json

 

{

"to" : "john.smith@test.com",

"subject" : "Test Email Message",

"email" : {

"body" : "Email Body goes here.",

"footer" : "Email signature goes here.",

"type" : "text/plain"

}

}

{{codeEnd}}

Request Body Details

to

(required)

String

The recipient's email address

subject

(required)

String

The subject line of the email message

body

(required)

String

The content of the email message. In the case of rich emails please see more details on how to fill this value in the section below

type

(required)

String

Either "text/plain" or "text/html" to describe the content of the message

footer

String

The email footer, often used to host the signature

Whispir’s support of rich (HTML) emails

  • JavaScript is not supported and should not be used in email messages
  • The html, head and body HTML elements are not supported. HTML content assumes that it’s starting from within the body tag
  • HTML form and input elements are not supported in most email clients. You can include them in the HTML content but you should thoroughly test them prior to use
  • STYLE elements are supported. Whispir recommends using a single style element at the top of the HTML that defines the styles for the entire email. However inline styles are also supported
  • Images must be referenced through absolute web URLs. Any other mechanism will not work on most email clients. Whispir doesn't host images for clients, so you must use another hosting service to reference the image’s URL in the request payload

Once the preceding rules are respected, when it comes to submitting HTML content in the body field of the JSON payload please follow these two simple rules in order to avoid the usage of libraries to escape and/or encode your HTML content:

  • replace all the HTML double quotes of your HTML content with single quotes: HTML treats them indifferently but this will avoid confusion when it will become JSON payload
  • minify the resulting HTML code, so that it lives on one line and can be loaded as a valid JSON field value

When instead you need to submit HTML content in the body field of an XML payload just be sure that the HTML content is submitted in this format [full example below]:

<![CDATA[ HTML_content  ]]>

  • JSON
  • XML

Sending rich text (HTML) emails

{{codeStart}}

# To send from a User-defined workspace

POST https://api.<region>.whispir.com/workspaces/:workspace_id/messages 

# To send from the default workspace

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

Accept: application/vnd.whispir.message-v1+json

{

"to" : "john.smith@test.com",

"subject" : "Test Email Message",

"email" : {

"body" : "<div id='content'><p>This is my content</p></div>",

"type" : "text/html"

}

}

{{codeEnd}}

Including attachments in email messages

The Whispir API provides users with the ability to compose email messages that also contain message attachments.

Attachments can be of any type [e.g. PDF, images and documents], and the maximum size of all attached files combined is 10 MB

Attachments must be provided in the payload of the message. URLs can be referenced in the email but will not be added as message attachments.

Important! The attachment element is a JSON array, so be sure to add the square brackets!

  • JSON
  • XML

Sending emails with attachments

{{codeStart}}

# To send from a User-defined workspace

POST https://api.<region>.whispir.com/workspaces/:workspace_id/messages 

# To send from the default workspace

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.message-v1+json

Accept: application/vnd.whispir.message-v1+json

{

"to" : "jsmith@test.com",

"subject" : "Test e-mail message with attachment",

"email" : {

"body" : "This is my content",

"type" : "text/plain",

"resources" : {

"attachment" : [{

"attachmentName" : "TestIcon.png",

"attachmentDesc" : "TestIcon.png",

"derefUri" : "iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAIAAADUsmlHAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAMvSURBVDhPTVT5S1RhFD3fezOOOePTXHKriWgjsogWC1TSMuuHIFqoX0KsIIgSWwiq/6FFU8MKK6KyXYSKpkUKR4QMSSpCLQpyxHHUZpztzdu63xub5vKWj/fu+c6599z3mMfjSU9P13UdZoiCaLfZYQWiUGKq1WrBLEBDOBpWNTWeQyEIwvT0NAsEAgROPKXFxceNbQOtv4ShkKCkaZZ5kYU1Sw6dqT0NMTkLBIbf7zf+xaOuJzgG4RmyPyP/Kwq/oWAYeT+R6gYOofnmlUQmLQjI6JQkifasu368KdCQWwFEwBiYQOIgiDBETDFIORh/iZ0De55cehgXQJIphce9d/ebJhuyV0P3QY9Cj/HDUKhseIPomP/CW2QYB42nSx+db76YUM9IusPhYHVM2g5Bpo5xNuIkZibCF8On0oGVjhWabmR8EBx5GDuHaItsy0zhzA6bo/H5ZSyDMQ1d4YQa0Sqc1hdAe3E7IYkqp9tiUcHGkXIQZ8+fm+k5uXK3/46YAV3mMMLEt/BHUJ1Vua9oH+WV9ayLyLpVhRYFkT8d4mUzRuI0DAcHmQngSLrGoBJ/GC/L31JSy/cm91ifXTcboYDJGLX+1kI6WS3AQFSRCUDvwhGEwubiD1yVLkLKWuxoT50kzGwab6Ru6HIsahpiwTybkwTLU9iUU1Ezf394CmuyV20p2kLg8mcbRHLLxGimLlWFFMpMc6TRFlx29aJqePBgx4M3u7tubb1dMXfjw6rHhOwb+/jhV3+qNtMFKspQEZnA+oxSPr9UdjgUllV59pHZhSUFI/We5AnMv5o7bvhsFu5f3DlmR7ATr/a+rtq2mVulqEqmlFlbUuv5MbqudW0C7PrhGpvwidRhIoyXqiHoRam/tGrT5n9Wmfcb9TfmBOf0DXy80H0h/uKU6yQRcqlmk+mji0RhbbN2XOpAygzF/9nmfp4oc4+4y6vLqRnuUTdsfNqYFRop/4JFw4t723qz52YlZpvPd/K30vm+03nAie1ADXAYOADsgHOXs/laix7RkzMJyJJ/BjQ09lQ7me8f9/cP9nsnvemzpOIFy3PzclkK0wyNgvDEHP8Z/AXQ58rAz69IBAAAAABJRU5ErkJggg=="

}]

}

}

}

{{codeEnd}}

Request Body Details

In addition to the parameters seen above, these are the ones related to the email with attachments:

attachmentName

(required)

String

The name of the attachment, including the extension

derefUri

(required)

String

The Base64 encoded value for the email attachment

attachmentDesc

String

A description for the attachment

Sample response

202 - Accepted

In this case the Location header in the Response Headers will show the direct link to the message. Depending on the endpoint of choice we will respectively have:

https://api.<region>.whispir.com/workspaces/:workspace_id/messages/:message_id

https://api.<region>.whispir.com/messages/:message_id

NOTE: if the Location Header containing the message_id wasn't collected at the time of sending please refer to Retrieve a previously sent message. This process is same for SMS, email, voice and push notifications