Docs - Inkit

Documentation. Whether you're a startup or a global enterprise, learn how to integrate with Inkit to connect to hundreds of vendors online. Instantly leverage global vendor infrastructure with our developer-friendly APIs.

Get Started    

Inkit Letters API

reading time 7 minutes

The guide how to use Letters API.

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.

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: PDF URL

In the case you have a PDF ready for print, use this data below to send to the webhook. Also, make sure that your PDF file is publicly available (even if that is temporary) for Inkit to receive the file.

📘

FieldTypeDescription
urlstringA URL to a pdf document containing the letter (one sided, one page).
first_namestringThe first name of the contact.
last_namestringThe last name of the contact. (optional)
emailstringThe email address for contact. (optional)
companystringThe company name that contact belongs to (optional)
phonestringThe phone number of the contact (optional)
address_line_1stringThe primary line, or street address of the contact (64-character limit)
address_line_2stringThe apartment or suite number. (optional)
address_citystringThe city for the contact's address
address_statestringThe two-letter (2) state code.
address_zipstringThe ZIP Code of the contact's address
address_countrystringThe two-letter (2) ISO alpha-2 country code of the contact's address
address_placementstringThe placement of the address, either top_first_page or insert_blank_page
double_sidedbooleantrue or false to force single-side printing.
colorbooleantrue means colored letter, false - black and white
mail_typeenum(usps_first_class, usps_standard)Determines whether or not to send the letter out as first_class or standard.
return_envelopebooleanDetermines if a return envelope is placed inside the mailed letter. Default false

Method 2: HTML

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

📘

FieldTypeDescription
htmlstringPlace HTML code here.
first_namestringThe first name of the contact.
last_namestringThe last name of the contact. (optional)
emailstringThe email address for contact. (optional)
companystringThe company name that contact belongs to (optional)
phonestringThe phone number of the contact (optional)
address_line_1stringThe primary line, or street address of the contact (64-character limit)
address_line_2stringThe apartment or suite number. (optional)
address_citystringThe city for the contact's address
address_statestringThe two-letter (2) state code.
address_zipstringThe ZIP Code of the contact's address
address_countrystringThe two-letter (2) ISO alpha-2 country code of the contact's address
address_placementstringThe placement of the address, either top_first_page or insert_blank_page
double_sidedbooleantrue or false to force single-side printing.
colorbooleantrue means colored letter, false - black and white
mail_typeenum(usps_first_class, usps_standard)Determines whether or not to send the letter out as first_class or standard.
return_envelopebooleanDetermines 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 3: 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

📘

FieldTypeDescription
template_idstringA template_id found on Inkit's Letters Template feature.
first_namestringThe first name of the contact.
last_namestringThe last name of the contact. (optional)
emailstringThe email address for contact. (optional)
companystringThe company name that contact belongs to (optional)
phonestringThe phone number of the contact (optional)
address_line_1stringThe primary line, or street address of the contact (64-character limit)
address_line_2stringThe apartment or suite number. (optional)
address_citystringThe city for the contact's address
address_statestringThe two-letter (2) state code.
address_zipstringThe ZIP Code of the contact's address
address_countrystringThe two-letter (2) ISO alpha-2 country code of the contact's address
address_placementstringThe placement of the address, either top_first_page or insert_blank_page
double_sidedbooleantrue or false to force single-side printing.
colorbooleantrue means colored letter, false - black and white
mail_typeenum(usps_first_class, usps_standard)Determines whether or not to send the letter out as first_class or standard.
return_envelopebooleanDetermines 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 Return Address

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

📘

FieldIs Required
return_namefalse if company is not empty otherwise true
return_companyfalse if name is not empty otherwise true
return_address_line_1true
return_address_line_2false
return_address_cityRequired if address_country is US, otherwise optional.
return_address_stateRequired 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_zipRequired and must follow the ZIP format of 12345 or ZIP+4 format of 12345-1234 if address_country is US, otherwise optional
return_address_countryfalse. 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 always happy to help with code or other questions you might have.
Search our documentation, check the help center, or connect with our sales team.
Ask questions to our support team ([email protected]) if you run into any technical roadblock or the links above are not helpful.

Updated about a month ago


What's Next

Authentication

Inkit Letters API


reading time 7 minutes

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.