Skip to main content

​
Overview

Recipients represent the individual or entity to whom you are sending mail. They can be created, updated, and managed through these endpoints. A mailing list ID is required when creating a recipient.

​
Naming

A recipient name is not required. In this case ‘Resident’ will be used. You can also just specify a company using the company field. The company field can also be used to add a secondary name (such as a spouse).

​
Addressing

The address field can be used to specify the recipient’s street address or it can also be used to specify the full address (in which case we’ll autoparse and split into fields automatically).

​
Lookup by Email

If no/invalid address is specified and a valid email address is, we’ll attempt to look up a valid street address using the email address for a fee.

​
Additional fields

custom1 through custom10, phone, and email can all be specified to help identify the recipient. The custom fields can also be used as replacement variables: %CUSTOM1% through %CUSTOM10% in messages, ~CUSTOM1~ through ~CUSTOM10~ in image templates, and in QR Code URLs.

​
Absentee (property) address

Use absentee_address when the property a mailer is about is not where the recipient gets mail — for example, an absentee owner who lives elsewhere. Set address to where the mail should go and absentee_address to the property:
You can also pass the whole property address in absentee_address on its own, for example "742 Evergreen Terrace, Springfield, IL 62704". absentee_city, absentee_province, and absentee_postal_code are optional, and only work alongside absentee_address. These variables then use the property address instead of the mailing address: The absentee fields work the same way when creating a recipient, when creating multiple recipients, and on each entry in recipients on the Send Mailer endpoints. Things to know:
  • The mailer is still delivered to address. The absentee fields only change what the variables above show.
  • Send the full address. Street View looks the property up from it, so a street line alone (742 Evergreen Terrace) can land on the wrong town. Include the city, state, and ZIP, either in absentee_address or in the separate fields.
  • It has its own field. The property address is stored as absentee_address, with any separate city, state, and ZIP joined into it (742 Evergreen Terrace, Springfield, IL 62704). Recipients and order items come back with absentee_address in API responses, and webhooks report it as recipient.absentee_address. You can set custom1 through custom10 alongside it. For templates built before this field existed, an empty custom2 is also filled with the absentee address, and follows it when you change or remove it; a custom2 you set yourself is never changed.
  • The older custom1/custom2 convention still works. Setting custom1 to absentee and custom2 to the property address has the same effect as absentee_address: the address is copied into absentee_address, and custom1 and custom2 are kept exactly as you sent them. If you send both, a non-empty absentee_address wins. Changing custom1 to anything other than absentee later removes the copied address.
  • Updating a recipient accepts the same fields. An update that leaves out absentee_address keeps the current absentee address. One that includes it replaces the stored address as a whole, so send absentee_address with any city, state, or ZIP you include: absentee_city, absentee_province, or absentee_postal_code on their own (for example, only a new ZIP) are refused with a 400 and nothing is updated. To remove the absentee address, send absentee_address as an empty string or null; if the recipient uses the older convention, that also clears the absentee value in custom1. Don’t send custom1 = absentee and a custom2 address in that same request, or the address is copied from custom2 instead of removed.
  • Without it, the variables fall back to the mailing address. ~STREET_VIEW~ and ~ABSENTEE_STREET~ show the recipient’s own address when no absentee address is set.