Start a conversation

curl --request POST \
  --url https://{organization}.rescueconsole.com/api/communications/threads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inbox_id": "c7d2e4f1-8a3b-4c5d-9e6f-1a2b3c4d5e6f",
  "person_id": "6d1f3a52-0b7e-4c1a-9d2f-5e8b7c4a1f20",
  "animal_ids": [
    "a3c9e1f4-2d6b-4f8a-b1c7-9e0d5f3a2b61"
  ],
  "subject": "Meet Biscuit on Saturday",
  "body_blocks": [
    {
      "type": "p",
      "runs": [
        {
          "text": "Hello Jordan,"
        }
      ]
    },
    {
      "type": "p",
      "runs": [
        {
          "text": "Biscuit is ready to meet you. Can you come to "
        },
        {
          "text": "Contoso Animal Rescue",
          "bold": true
        },
        {
          "text": " on Saturday at 10am?"
        }
      ]
    },
    {
      "type": "ul",
      "items": [
        [
          {
            "text": "Bring a photo ID"
          }
        ],
        [
          {
            "text": "Bring your dog, if you have one"
          }
        ]
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inbox_id: 'c7d2e4f1-8a3b-4c5d-9e6f-1a2b3c4d5e6f',
    person_id: '6d1f3a52-0b7e-4c1a-9d2f-5e8b7c4a1f20',
    animal_ids: ['a3c9e1f4-2d6b-4f8a-b1c7-9e0d5f3a2b61'],
    subject: 'Meet Biscuit on Saturday',
    body_blocks: [
      {type: 'p', runs: [{text: 'Hello Jordan,'}]},
      {
        type: 'p',
        runs: [
          {text: 'Biscuit is ready to meet you. Can you come to '},
          {text: 'Contoso Animal Rescue', bold: true},
          {text: ' on Saturday at 10am?'}
        ]
      },
      {
        type: 'ul',
        items: [[{text: 'Bring a photo ID'}], [{text: 'Bring your dog, if you have one'}]]
      }
    ]
  })
};

fetch('https://{organization}.rescueconsole.com/api/communications/threads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{organization}.rescueconsole.com/api/communications/threads"

payload = {
    "inbox_id": "c7d2e4f1-8a3b-4c5d-9e6f-1a2b3c4d5e6f",
    "person_id": "6d1f3a52-0b7e-4c1a-9d2f-5e8b7c4a1f20",
    "animal_ids": ["a3c9e1f4-2d6b-4f8a-b1c7-9e0d5f3a2b61"],
    "subject": "Meet Biscuit on Saturday",
    "body_blocks": [
        {
            "type": "p",
            "runs": [{ "text": "Hello Jordan," }]
        },
        {
            "type": "p",
            "runs": [{ "text": "Biscuit is ready to meet you. Can you come to " }, {
                    "text": "Contoso Animal Rescue",
                    "bold": True
                }, { "text": " on Saturday at 10am?" }]
        },
        {
            "type": "ul",
            "items": [[{ "text": "Bring a photo ID" }], [{ "text": "Bring your dog, if you have one" }]]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "thread_id": "<string>",
  "message_id": "<string>",
  "status": "sent",
  "to": "<string>",
  "to_addresses": [
    "<string>"
  ],
  "cc_addresses": [
    "<string>"
  ],
  "subject": "<string>"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "<string>",
  "reason": "<string>",
  "thread_id": "<string>",
  "message_id": "<string>"
}

Sending

Start a conversation

Opens a new conversation in one of your inboxes and sends its first message. This sends real email to real people, and it cannot be undone. Once the email service accepts a message it is on its way, and nothing can recall it. There is no test mode.

The message goes out from your organization’s sending address, and replies to it come back into this conversation. The people it is to and copied to, the animals, and the record named are linked to the conversation, confirmed, so it shows on their records.

What stops it, before anything is sent or any conversation is opened:

A merge field such as {{first_name}} is left anywhere in the subject or body (400). Fill templates first with Fill a template.
Any address it goes to or copies is suppressed (409). Nothing is sent to anybody.
Any person named in person_id, person_ids or cc_person_ids has opted out of email altogether, or out of the category general (409). Typed addresses are not checked against anybody’s preferences.
Your organization cannot send email yet, for example while its own sending domain waits to be verified (409).

If the email service refuses the message, the answer is 502: the conversation and the message are kept, marked as not sent, and the reason is in reason.

A key sees the inboxes that the person who made the key may read, as that person’s access stands at the moment of the request; a conversation in any other inbox answers 404, the same as one that does not exist. Needs write on Communications.

POST

api

communications

threads

Start a conversation

curl --request POST \
  --url https://{organization}.rescueconsole.com/api/communications/threads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inbox_id": "c7d2e4f1-8a3b-4c5d-9e6f-1a2b3c4d5e6f",
  "person_id": "6d1f3a52-0b7e-4c1a-9d2f-5e8b7c4a1f20",
  "animal_ids": [
    "a3c9e1f4-2d6b-4f8a-b1c7-9e0d5f3a2b61"
  ],
  "subject": "Meet Biscuit on Saturday",
  "body_blocks": [
    {
      "type": "p",
      "runs": [
        {
          "text": "Hello Jordan,"
        }
      ]
    },
    {
      "type": "p",
      "runs": [
        {
          "text": "Biscuit is ready to meet you. Can you come to "
        },
        {
          "text": "Contoso Animal Rescue",
          "bold": true
        },
        {
          "text": " on Saturday at 10am?"
        }
      ]
    },
    {
      "type": "ul",
      "items": [
        [
          {
            "text": "Bring a photo ID"
          }
        ],
        [
          {
            "text": "Bring your dog, if you have one"
          }
        ]
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inbox_id: 'c7d2e4f1-8a3b-4c5d-9e6f-1a2b3c4d5e6f',
    person_id: '6d1f3a52-0b7e-4c1a-9d2f-5e8b7c4a1f20',
    animal_ids: ['a3c9e1f4-2d6b-4f8a-b1c7-9e0d5f3a2b61'],
    subject: 'Meet Biscuit on Saturday',
    body_blocks: [
      {type: 'p', runs: [{text: 'Hello Jordan,'}]},
      {
        type: 'p',
        runs: [
          {text: 'Biscuit is ready to meet you. Can you come to '},
          {text: 'Contoso Animal Rescue', bold: true},
          {text: ' on Saturday at 10am?'}
        ]
      },
      {
        type: 'ul',
        items: [[{text: 'Bring a photo ID'}], [{text: 'Bring your dog, if you have one'}]]
      }
    ]
  })
};

fetch('https://{organization}.rescueconsole.com/api/communications/threads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://{organization}.rescueconsole.com/api/communications/threads"

payload = {
    "inbox_id": "c7d2e4f1-8a3b-4c5d-9e6f-1a2b3c4d5e6f",
    "person_id": "6d1f3a52-0b7e-4c1a-9d2f-5e8b7c4a1f20",
    "animal_ids": ["a3c9e1f4-2d6b-4f8a-b1c7-9e0d5f3a2b61"],
    "subject": "Meet Biscuit on Saturday",
    "body_blocks": [
        {
            "type": "p",
            "runs": [{ "text": "Hello Jordan," }]
        },
        {
            "type": "p",
            "runs": [{ "text": "Biscuit is ready to meet you. Can you come to " }, {
                    "text": "Contoso Animal Rescue",
                    "bold": True
                }, { "text": " on Saturday at 10am?" }]
        },
        {
            "type": "ul",
            "items": [[{ "text": "Bring a photo ID" }], [{ "text": "Bring your dog, if you have one" }]]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "thread_id": "<string>",
  "message_id": "<string>",
  "status": "sent",
  "to": "<string>",
  "to_addresses": [
    "<string>"
  ],
  "cc_addresses": [
    "<string>"
  ],
  "subject": "<string>"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "house_trained must be 1, 0 or null (not assessed)"
}

{
  "error": "<string>",
  "reason": "<string>",
  "thread_id": "<string>",
  "message_id": "<string>"
}

Authorizations

Authorization

string

header

required

An API key from Settings, API keys. It starts with rc_live_.

Body

application/json

Name at least one recipient: a person or an address. Send the body as body_blocks or as body. Every person named must have an email address on file.

inbox_id

string

required

The inbox to send from. It must be active and one this key may read.

subject

string

required

Minimum string length: 1

person_id

string

A person on file to write to.

person_ids

string[]

More people on file to write to, 20 at most.

Maximum array length: 20

An address, or a list of up to 20, to write to that is not a person on file.

cc_person_ids

string[]

People on file to copy, 20 at most.

Maximum array length: 20

An address, or a list of up to 20, to copy.

body_blocks

object[]

A message written as a document: at most 200 blocks.

One block of a document. An unknown type is refused.

Show child attributes

body

string

The body as plain text, when you do not send body_blocks.

template_id

string

The template this message started from, kept on the log entry. The template is not filled here: fill it first with Fill a template.

animal_ids

string[]

Animals the conversation is about, 20 at most.

Maximum array length: 20

The kind of record a conversation can be about.

Available options:

person,

organization,

animal,

location_unit,

donation,

campaign,

shift,

volunteer_event,

shift_signup,

adoption_application,

org_event,

form_submission

Send it with related_entity_type, or neither.

Response

Sent.

thread_id

string

required

message_id

string

required

The message's ID in the conversation.

status

enum<string>

required

Available options:

sent

string

The first recipient.

to_addresses

string[]

cc_addresses

string[]

subject

string

Using the API

Endpoints

Start a conversation

Authorizations

Body

Response