fastify-xhubspot

engagement.createEmail

Log an email engagement against a HubSpot contact.

engagement.createEmail

Create an email engagement and associate it with a HubSpot contact. This logs an outbound or inbound email on the contact timeline without sending the email itself.

Signature

fastify.engagement.createEmail(
  contactId: string,
  emailData: {
    subject?: string;
    body?: string;
    from?: string;
    to?: string;
    ownerId?: string;
  }
): Promise<{ id: string; properties: Record<string, string>; createdAt: string }>

Params

Name	Type	Required	Description
`contactId`	`string`	Yes	HubSpot contact ID to associate the email engagement with.
`emailData.subject`	`string`	No	Email subject line. Stored as `hs_email_subject`.
`emailData.body`	`string`	No	Email body text. Stored as `hs_email_text`.
`emailData.from`	`string`	No	Sender email address. Stored as `hs_email_from`.
`emailData.to`	`string`	No	Recipient email address. Stored as `hs_email_to`.
`emailData.ownerId`	`string`	No	HubSpot owner ID to credit the email to. Stored as `hubspot_owner_id`.

Returns

Field	Type	Description
`id`	`string`	HubSpot engagement ID for the email record.
`properties`	`object`	Stored properties including `hs_email_subject`, `hs_email_text`, `hs_email_direction` (`"EMAIL"`), `hs_timestamp`.
`createdAt`	`string`	ISO 8601 creation timestamp.

Throws

[xHubspot] engagement.createEmail requires a contactId — if contactId is missing.
[xHubspot] engagement.createEmail requires an emailData object — if emailData is not an object.
Re-throws the HubSpot API error on network failure after logging via fastify.log.error.

Examples

Basic — log a sent email

const email = await fastify.engagement.createEmail("12345", {
  subject: "Your trial is starting soon",
  body: "Hi Alice, your 14-day trial begins tomorrow...",
  from: "sales@example.com",
  to: "alice@acme.com",
});

console.log(email.id); // "55321"

Realistic — log a transactional email after send

fastify.post("/emails/send", async (request, reply) => {
  const { contactId, subject, body, senderEmail, ownerId } = request.body;

  // Send via your email provider first
  await sendEmail({ to: request.body.recipientEmail, subject, body });

  // Then log it in HubSpot
  const engagement = await fastify.engagement.createEmail(contactId, {
    subject,
    body,
    from: senderEmail,
    to: request.body.recipientEmail,
    ownerId,
  });

  return reply.send({ engagementId: engagement.id });
});

AI Context

package: "@xenterprises/fastify-xhubspot"
method: fastify.engagement.createEmail(emailData)
use-when: Log an email engagement against a HubSpot contact
params: { subject, body, contactId, ownerId? }
returns: { id, properties }

Edit this pageorReport an issue

engagement.createCall

Log a call engagement against a HubSpot contact.

engagement.createNote

Log a text note against a HubSpot contact.