Letters

This API endpoint uses an HTTP POST request. You must provide an Authorization header, which can be found under the settings section in the Inkit application.

📘

Authentication setup

You can find more information about Authentication here
Authentication

Letters Webhook Endpoint: https://internal.inkit.io/integrations/letters-webhook

To use this feature you will need to use cURL, Postman, or setup an automatic endpoint trigger within your system with the following data structure, described below (depends on the method you will choose).

Method 1: HTML

For creating a more flexible letter with customized data fields, use HTML.

📘

Field	Type	Description
html	string	Place HTML code here.
first_name	string	The first name of the contact.
last_name	string	The last name of the contact. (optional)
email	string	The email address for contact. (optional)
company	string	The company name that contact belongs to (optional)
phone	string	The phone number of the contact (optional)
address_line_1	string	The primary line, or street address of the contact (64-character limit)
address_line_2	string	The apartment or suite number. (optional)
address_city	string	The city for the contact's address
address_state	string	The two-letter (2) state code.
address_zip	string	The ZIP Code of the contact's address
address_country	string	The two-letter (2) ISO alpha-2 country code of the contact's address
address_placement	string	The placement of the address, either top_first_page or insert_blank_page
double_sided	boolean	true or false to force single-side printing.
color	boolean	true means colored letter, false - black and white
mail_type	enum(usps_first_class, usps_standard)	Determines whether or not to send the letter out as first_class or standard.
return_envelope	boolean	Determines if a return envelope is placed inside the mailed letter. Default false

📘

You may insert custom fields by using two percentage signs on both sides of the variable.
Example:

%% custom_name %%

Ensure that "custom_name" field is inside the data payload of your API call.

{
  the main fields,
  "custom_name": "Elon Musk"
}

Method 2: Template ID

You can use Inkit's Letters Template feature to create an HTML letter. Then use the provided template_id in the request.

Follow this link to set up a letters template: https://app.inkit.io/#/letters-templates

📘

Field	Type	Description
template_id	string	A template_id found on Inkit's Letters Template feature.
first_name	string	The first name of the contact.
last_name	string	The last name of the contact. (optional)
email	string	The email address for contact. (optional)
company	string	The company name that contact belongs to (optional)
phone	string	The phone number of the contact (optional)
address_line_1	string	The primary line, or street address of the contact (64-character limit)
address_line_2	string	The apartment or suite number. (optional)
address_city	string	The city for the contact's address
address_state	string	The two-letter (2) state code.
address_zip	string	The ZIP Code of the contact's address
address_country	string	The two-letter (2) ISO alpha-2 country code of the contact's address
address_placement	string	The placement of the address, either top_first_page or insert_blank_page
double_sided	boolean	true or false to force single-side printing.
color	boolean	true means colored letter, false - black and white
mail_type	enum(usps_first_class, usps_standard)	Determines whether or not to send the letter out as first_class or standard.
return_envelope	boolean	Determines if a return envelope is placed inside the mailed letter. Default false

🚧

Note

By default, the account's return address is used. This can be edited at https://app.inkit.io/#/account/organization/address. Alternatively, this may be overwritten and customized by placing return address information with prefix return_ (see below).

Optional: Overwriting Your Return Address

Return addresses may be overwritten by including the following fields in your payload. Make sure to include each field marked "required."

📘

Field	Is Required
return_name	false if company is not empty otherwise true
return_company	false if name is not empty otherwise true
return_address_line_1	true
return_address_line_2	false
return_address_city	Required if address_country is US, otherwise optional.
return_address_state	Required and must be a 2 letter state short-name code or a valid full state name if address_country is US, otherwise optional
return_address_zip	Required and must follow the ZIP format of 12345 or ZIP+4 format of 12345-1234 if address_country is US, otherwise optional
return_address_country	false. Must be a 2 letter country short-name code (ISO 3166). Defaults to US

🚧

Missing required fields

If any of the fields marked as required are missing from the request - the default return address under the account settings will be used instead.

Finalized Request Example

curl --header "Authorization: Inkit <api-key>" -d 
'{
"html": "<html> <h1> Dear Elon,  </h1><p> Say hi from space. </p>  </html>",
"first_name": "Elon",
"last_name": "Musk",
"email":"[email protected]",
"company":"SpaceX",
"phone":"3107099497",
"address_line_1": "1 Rocket Road",
"address_line_2": "Suite 1",
"address_city": "Hawthorne",
"address_state": "CA",
"address_zip": "90250",
"address_country": "US",
"address_placement": "top_first_page",
"double_sided": "False",
"color": "False",
"mail_type": "usps_first_class",
"return_company": "Inkit",
"return_name": "Matt McCullough",
"return_address_line_1": "619 S 10th St.",
"return_address_line_2": "Suite 301",
"return_address_city": "Minneapolis",
"return_address_state": "MN",
"return_address_zip": "55404",
"return_address_country": "US",
 }'
-H "Content-Type: application/json" -X POST https://internal.inkit.io/integrations/letters-webhook

Response

202 Accepted HTTP response will be returned for successful post request.
Otherwise, you will receive an error message. The meaning of them you can find here.

Questions?

We're happy to help get your code set up or answer questions you might have.
Search our documentation, check the help center, or connect with our sales team.
Ask our support team ([email protected]) questions if you run into any technical roadblocks.