Postal Mail

OverviewEndpoints

Use the postal mail engagement API to log and manage postal mail on CRM records. You can log the mail you've sent or received in HubSpot or through the postal mail API. You can also retrieve, update, or delete existing postal mail engagements. 

Below, learn the basic methods of managing postal mail through the API. To view all available endpoints and their requirements, click the Endpoints tab at the top of this article.

Create a postal mail engagement

To create a postal mail engagement, make a POST request to /crm/v3/objects/postal_mail.

In the request body, add postal mail details in a properties object. You can also add an associations object to associate your new postal mail with an existing record (e.g., contacts, companies).

Properties

In the properties object, you can include the following fields:

Use this table to describe parameters / fields
FieldDescription
hs_timestamp

The date that the postal mail was sent or received.

hs_postal_mail_body

The body text of the postal mail engagement.

hubspot_owner_id

The ID of the user that created the postal mail engagement.

hs_attachment_ids

The IDs of any attachments to the postal mail engagement. Multiple attachment IDs are separated by a semi-colon.

Associations

To create and associate a postal mail engagement with existing records, include an associations object in your request. The object should include the following fields:

Use this table to describe parameters / fields
ParameterDescription
toObjectId

The ID of the record that you want to associate the postal mail with.

associationTypeId

A unique identifier to indicate the association type between the postal mail and the other object. You can retrieve the value through the associations API.

For example, to create postal mail and associate it with two contacts, your request body might look similar to the following:

//Example request body { "properties": { "hs_timestamp": "2021-11-12", "hs_postal_mail_body": "Sent copy of contract to decision maker John", "hubspot_owner_id": "9274996", "hs_attachment_ids": "24332474034" }, "associations": [ { "to": { "id": 501 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 453 } ] }, { "to": { "id": 502 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 453 } ] }] }

Retrieve postal mail engagements

You can retrieve postal mail engagements individually or in bulk.

To retrieve an individual postal mail engagement, make a GET request to /crm/v3/objects/postal_mail/{postalMail}. You can include the following parameters in the request: 

Use this table to describe parameters / fields
ParameterDescription
properties

A comma separated list of the properties to be returned. 

associations

A comma separated list of object types to retrieve associated IDs for. Any specified associations that don't exist will not be returned in the response. Learn more about the associations API.

To retrieve a list of the postal mail engagements in your account, make a GET request to crm/v3/objects/postal_mail. You can include the following parameters in the request:

Use this table to describe parameters / fields
ParameterDescription
limit

The maximum number of results to display per page.

properties

A comma separated list of the properties to be returned. 

When you make a successful batch request, the response will include the ID of each postal mail engagement, which you can use to retrieve, update, and delete postal mail engagements.

Update postal mail engagements

You can update postal mail engagements individually or in batches. To update an individual engagement by its ID, make a PATCH request to /crm/v3/objects/postal_mail/{postalMail}. 

In the request body, include the properties that you want to update. For example, to update the body of the engagement, your request body might look similar to the following:

//Example request body { "properties": { "hs_postal_mail_body": "Sent copy of contract to decision maker John. Received a call in response." } }

HubSpot will ignore values for read-only and non-existent properties. To clear a property value, pass an empty string for the property in the request body.

Learn more about batch updating by clicking the Endpoints tab at the top of this article.

Associate existing postal mail with records

You can associate postal mail engagements with contact, company, deal, or ticket records. To associate postal mail with records, make a PUT request to /crm/v3/objects/postal_mail/{postalMail}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. 

Use this table to describe parameters / fields
ParameterDescription
postalMail

The unique ID of the postal mail engagement.

toObjectType

The type of object that you want to associate the postal mail with (e.g., contact or company).

toObjectId

The ID of the record that you want to associate the postal mail with.

associationTypeId

A unique identifier to indicate the association type between the postal mail and the other object. The ID can be represented numerically or in snake case (e.g., POSTAL_MAIL_TO_CONTACT). You can retrieve the value through the associations API.

For example, your request URL might look similar to the following:

https://api.hubspot.com/crm/v3/objects/postal_mail/25727582880/associations/contact/104901/POSTAL_MAIL_TO_CONTACT

Remove an association

To remove an association between a postal mail engagement and a record, make a DELETE request to:

/crm/v3/objects/postal_mail/{postalMail}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

Delete postal mail engagements

You can delete a postal mail engagement individually or in bulk, which will add the engagement to the recycling bin in HubSpot. You can later restore the engagement from the record timeline.

To delete an individual postal mail engagement by its ID, make a DELETE request to /crm/v3/objects/postal_mail/{postalMail}.

Learn more about batch deleting postal mail engagements on the Endpoints tab at the top of this article.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.