Knock Log Email API is part of Knock’s effort to expand its API suite to include the ability for 3rd party vendors to log messages to Knock guest cards so that leasing teams in Knock have context and analytics on conversations that took place outside of Knock.
This endpoint does not send an email to a prospect. It only logs an email interaction. An email logged through this endpoint will be identical to how an email is sent through Knock today. This includes prospect being removed from the to-do list if it is the first time a prospect is being contacted, prospect’s being moved from New to Open, prospect response times being updated if it is the first response to a prospect, and email events being logged in analytics in the same way emails are logged in analytics today.
Below is a picture of a sample email that was sent from a manager to a prospect. Note how the vendor that was responsible for the email is also being noted in the very bottom of the picture, the “via Syndication Service - Stage - SSO” text.
This article contains the technical documentation and details for developers to get started using the Log Email API.
The general flow will be:
-
Partner needs to create a prospect and save the prospectId from the response payload. A prospect can be created via the Knock Prospect Creation API
-
Note: Currently we do not expose the prospectId, therefore the parter needs to save it from the Prospect Creation API response payload
-
Now the partner can call the log email using the log email endpoint, POST :/prospect/{prospectId}/email, with the prospectId and fill in the parameters
Log Email Creation
Log a prospect email through our Log Email endpoint. You can use the API endpoint to log prospect email interactions that concern a particular property, which is POST :/prospect/{prospectId}/email. For more details on the parameters, check out our swagger documentation here: stage documentation, production documentation.
The following includes the path parameter in the request endpoint.
-
prospectId (string)
-
The Id of the prospect the manager is communicating with.
-
The following are a list of the request body parameters. Note, that all these body parameters are required.
-
type (string)
-
Type of message being logged. There are 3 types to choose from:
-
EMAIL_MESSAGE_TO_PROSPECT_SENT, email sent from a leasing agent or contracted representative to the prospect, -
EMAIL_MESSAGE_FROM_PROSPECT_RECEIVED, email sent from prospect to the property, and -
EMAIL_AUTOMATED_MESSAGE_SENTautomated email sent to prospect.
-
-
-
sentTime (iso date-time string)
-
Time the email was sent
-
-
agent.username (string)
-
Username of the agent interacting with the prospect.
-
-
subject (string)
-
Subject field of the email.
-
-
body (string)
-
Message body of the email. HTML is accepted in the body as well. Check example below for clarity.
-
The following example demonstrates this using the JavaScript fetch API:
1const API_KEY = "syndication-appointment-TEST-KEY"; 2 3const logEmail = async (prospectId) => { 4 const req = { 5 "type": "EMAIL_MESSAGE_TO_PROSPECT_SENT", 6 "sentTime": "2020-03-31T23:22:06.214Z", 7 "agent":{ 8 "username": "e5e42ae3-a3fa-48ae-a5c5-92ca704d38ad" 9 }, 10 "subject": "email subject" 11 "body": "<html>Hello World Email</html>" 12 }; 13 const endpoint = `https://stage-syndication.knockrentals.com/prospect/${prospectId}/email`; 14 const res = await fetch(endpoint, { 15 body: JSON.stringify(req), 16 headers: { 17 "Content-Type": "application/json", 18 "x-api-key": API_KEY 19 }, 20 method: "POST" 21 }); 22 23 const resp = await res.json(); 24 25 if (res.status === 200) { 26 // Success, e.g. ` 27 // `{ 28 // “communicationId: “4WXU6U2J-37444208” 29 // }` 30 // 31 console.log(resp); 32 } else { 33 // Failure: details at resp.errorMessage 34 console.error(resp); 35 } 36}; 37 38logEmail(1); 39
40
Comments
Article is closed for comments.