Messages
========

Message Types
-------------

:email:
	a "normal" email bcc's into Sheep
:templated:
	a templated message generated in Sheep delivered by email
:templated-in-app:
	a templated message generated in Sheep delivered through the app
:templated-sms:
	a templated message generated in Sheep delivered through the SMS **additional costs apply**
:templated-post:
	(future) a templated message generated in Sheep printed on demand and posted **additional costs apply**

Message Status
--------------

:draft:
	initial / draft state
:sent:
	a successfully handed off to the delivery system
:received:
	used for external emails
:queued:
	waiting to be handed to the delivery system
:failed:
	the generation or delivery system reported a failure
:failed_multi:
	the generation or delivery system reported a 2nd failure
:fatal:
	a serious issue with message generation of delivery


Template fields
^^^^^^^^^^^^^^^

:process_date:
	rendering date/time
:regarding:
	additional data to use in the template rendering
:acknowledgement_date:
	date email acknowledgement by user
:date:
	date on email
:from:
	email of user sending / system account
:from_reference:
	sheepCRM contact reference of sender
:html_message:
	the rendered template
:text_message:
	the rendered template
:raw:
	the raw template
:status:
	see message status list above
:subject:
	email subject from template
:to_reference:
	sheepCRM contact reference of recipient
:type:
	message delivery type
:uid:
	system unique ID
:requires_acknowledgement:
	for use with in-app messages to collect acknowledgement


External email fields
^^^^^^^^^^^^^^^^^^^^^

:acknowledgement_date:
	date email processed by sheepCRM
:cc_reference:
	sheepCRM contact reference list
:date:
	date on email
:files:
	list of file attachments (posted to S3)
:from:
	email of sender (text)
:from_reference:
	sheepCRM contact reference of sender
:html_message:
	message body as html
:text_message:
	message body as text (html may be converted to text)
:raw:
	raw message body
:status:
	will always be "received"
:subject:
	email subject
:to:
	message recipient (text)
:to_reference:
	sheepCRM contact reference of recipient
:uid:
	IMAP message uid

Creating a message
------------------

.. code-block:: http


	http POST https://api.sheepcrm.com/api/v1/example/message/ "Authorization: Bearer $API_KEY" to_reference=/example/person/5e7cf08e80859e2e284749a8/ subject="hello" raw="hi {{first_name}}" type=templated

	HTTP/1.0 200 OK

	{
	    "bucket": "example",
	    "data": {
	        "date": "2021-06-29T10:03:10.311000",
	        "delivery_status": null,
	        "raw": "hi {{first_name}}",
	        "status": "draft",
	        "subject": "hello",
	        "to_reference": [
	            {
	                "display_value": "James Webster",
	                "ref": "/example/person/5e7cf08e80859e2e284749a8/"
	            }
	        ],
	        "type": "templated",
	        "uid": null
	    },
	    "uri": "/example/message/60daefde0a7750b55c83a257/"
	}

The message record has been created as a draft message. This can be previewed to check the body rendering.

.. code-block:: http


	http https://api.sheepcrm.com/api/v1/example/message/60daefde0a7750b55c83a257/preview/ "Authorization:

	{
	    "bucket": "example",
	    "data": {
	        "acknowledgement_date": null,
	        "cc_reference": [],
	        "content": {
	            "/example/person/5e7cf08e80859e2e284749a8/": {
	                "html": "<p>hi James</p>\n",
	                "text": "hi James"
	            }
	        },
	        "date": "2021-06-29T10:03:10.311000",
	        "delivery_status": null,
	        "emails": {
	            "/example/person/5e7cf08e80859e2e284749a8/": "james@sheepcrm.com"
	        },
	        "errors": {
	            "/example/person/5e7cf08e80859e2e284749a8/": null
	        },
	        "raw": "hi {{first_name}}",
	        "status": "draft",
	        "subject": "hello",
	        "subjects": {
	            "/example/person/5e7cf08e80859e2e284749a8/": "hello"
	        },
	        "to_reference": [
	            {
	                "display_value": "James Webster",
	                "ref": "/example/person/5e7cf08e80859e2e284749a8/"
	            }
	        ],
	        "type": "templated",
	        "uid": null
	    },
	    "resource": "message",
	    "uri": "/example/message/60daefde0a7750b55c83a257/"
	}

The content section show the html and text rendering: e.g.

::

	'html': '<p>hi James</p>\n'
	'text': 'hi James'


Sending a message
-----------------

Test send the message
^^^^^^^^^^^^^^^^^^^^^

Test the message by sending you yourself (the email associated with the API KEY). The preview shows the rendering but to see the full email within the wider html template send an actual test message and check it in your email client.

.. code-block:: http


	http POST https://api.sheepcrm.com/api/v1/example/message/60daefde0a7750b55c83a257/testsend/ "Authorization: Bearer $API_KEY"

Send the message
^^^^^^^^^^^^^^^^

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/example/message/60daefde0a7750b55c83a257/send/ "Authorization: Bearer $API_KEY"

Queue and send
^^^^^^^^^^^^^^

For large numbers of recipients send asynchronously (each email is rendered and sent individually so sending is slow.)

.. code-block:: http

	http POST https://api.sheepcrm.com/api/v1/example/message/60daefde0a7750b55c83a257/queue_and_send/ "Authorization: Bearer $API_KEY"