Letters

<div class="ink-cat-header"> The how-to guide for the Letters API. </div>

<div class="ink-hr"></div>

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](doc: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).

## <div class="ink-heading"> Method 1: HTML </div>

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.
>
> <pre>{<br/>  the main fields,<br/>  "custom_name": "Elon Musk"<br/>}</pre>

## <div class="ink-heading"> Method 2: Template ID </div>

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](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](https://app.inkit.io/#/account/organization/address). Alternatively, this may be overwritten and customized by placing return address information with prefix `return_` (see below).

## <div class="ink-heading"> Optional: Overwriting Your Return Address </div>

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.

## <div class="ink-heading"> Finalized Request Example </div>

```curl
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