--- title: Braze | PostGrid description: Integrate PostGrid with Braze to automate sending letters, postcards, cheques, and self-mailers using Braze webhooks. --- ## Overview This guide provides step-by-step instructions for integrating PostGrid’s mailing services with Braze, enabling you to automate the process of sending letters, postcards, cheques, and self mailers to your users. By leveraging PostGrid’s API and Braze’s webhook functionality, you can easily create webhook templates, ensuring a seamless and efficient mailing experience. Use this guide as an additional resource to the [Braze webhook documentation](https://www.braze.com/docs/user_guide/message_building_by_channel/webhooks/understanding_webhooks). ## Prerequisites - A PostGrid account - PostGrid API keys ## Add custom attributes to users To create an order on PostGrid, you need to specify the recipient’s mailing information, such as: - firstName - lastName - addressLine1 - addressLine2 (optional) - city - provinceOrState - postalOrZip - countryCode These are the essential data fields you must provide. For a comprehensive list of all attributes your contact can have, refer to the [PostGrid API documentation](https://docs.postgrid.com/#3ac81e66-c5be-4bb6-93c1-fd8a6f0a24b3). Some of these properties are not available by default in Braze. However, you can add custom attributes to your Braze users to add your recipient mailing information and any other additional attributes that you need (if you are using [merge variables](https://docs.postgrid.com/#merge-variables), for example). There are two ways of adding custom attributes to Braze.\ You can create new custom attributes in **Data Settings > Custom Attributes**. Learn more about adding custom attributes in [Braze’s documentation](https://www.braze.com/docs/user_guide/data_and_analytics/custom_data/custom_attributes). We will cover an alternative way of adding custom attributes in the next section (Update Braze users). ![Braze Custom Attributes page listing user-defined mailing fields like addressLine1 and city](/_astro/01-image.DHq7k3Hw_u72pz.webp) ## Update Braze users After creating the custom attributes, you can update your Braze users’ mailing information. You can update users via [API](https://www.braze.com/docs/api/endpoints/user_data/post_users_alias_update) or [CSV upload](https://www.braze.com/docs/user_guide/data_and_analytics/user_data_collection/user_import#importing-custom-data-via-csv). Sending custom attributes in your API request or during the CSV upload will create those custom attributes if they have not already been created. Braze will automatically set their name and data type, and you will be able to view them on the **Custom Attributes** page. Once updated, you’ll be able to view users’ custom attributes on their profile page. Note that for this example, we also added the additional property **invoiceNumber** which we will be using as a merge variable on our request. ![Braze user profile page showing custom attributes including addressLine1, city, and invoiceNumber](/_astro/02-image.BENMuSVC_2mSoxJ.webp) ## Create a webhook template Follow the steps on [Braze documentation](https://www.braze.com/docs/user_guide/message_building_by_channel/webhooks/webhook_template) to create a webhook template. On the creation page, fill out the following fields: Webhook URL: \\ HTTP method: POST\ Request Body: Raw Text You will need to replace \ with the PostGrid endpoint you would like to use, depending on the action you’d like to perform on your PostGrid account. The available Print & Mail endpoints include: | Host | Endpoint | | :-------------------------- | :----------------------------------------------------------------------------------------------------------------------- | | | print-mail/v1/letters, print-mail/v1/postcards, print-mail/v1/self\_mailers, print-mail/v1/cheques?expand\[]=bankAccount | Check the [PostGrid API documentation](https://docs.postgrid.com/) for a complete list of endpoints. In the following sections, we will cover some key points to consider when creating an order with PostGrid. ## Select a template for your mailing To send your mailings, you will need to select a template (the document containing the actual mailing content). On PostGrid, you can either use raw HTML, a PDF file, or an existing template that you have created on PostGrid’s [Template Editor](/print-and-mail/dashboard/using-our-built-in-template-editor/index.md). When working with PDF files, you will need to supply a link to a PDF hosted somewhere publicly accessible in your request. See the example below for creating a letter: ``` { "description": "Braze Webhook test", "to": { "firstName": "", "lastName": "", "addressLine1": "", "addressLine2": "", "city": "", "provinceOrState": "", "postalOrZip": "", "countryCode": "" }, "from": "", "pdf": "https://pg-prod-bucket-1.s3.amazonaws.com/live/usr_9m6FVmm78VxXhtkKjARXnE/ltr_6YgdBFHXL2axmqzKY8EEu8.pdf", "color": "true", "addressPlacement": "insert_blank_page", "doubleSided": false } ``` You can also use an existing template created on the Template Editor by supplying its ID on the request. You can find your template ID on the [Templates page](https://dashboard.postgrid.com/dashboard/templates) on PostGrid’s dashboard: ![PostGrid dashboard Templates page showing a list of templates with their IDs](/_astro/03-image.DA5Hbtii_2eHAIp.webp) ``` { "description": "Braze Webhook test", "to": { "firstName": "", "lastName": "", "addressLine1": "", "addressLine2": "", "city": "", "provinceOrState": "", "postalOrZip": "", "countryCode": "" }, "from": "", "template": "template_2tsUt2Nu1UEVMvuuATBT1g", "color": "true", "addressPlacement": "insert_blank_page", "doubleSided": false } ``` You can also send raw HTML in your request instead. For example: ``` { "description": "Braze Webhook test", "to": { "firstName": "", "lastName": "", "addressLine1": "", "addressLine2": "", "city": "", "provinceOrState": "", "postalOrZip": "", "countryCode": "" }, "from": "", "html": "Hello, {{to.firstName}}!", "color": "true", "addressPlacement": "insert_blank_page", "doubleSided": false } ``` In this example, we used merge variables in our HTML and you are also able to use them with existing templates. Check PostGrid’s documentation on [merge variables](https://docs.postgrid.com/#merge-variables) and our [guide on adding merge variables to a template for more information](/print-and-mail/dashboard/using-our-built-in-template-editor#adding-merge-variable-to-the-template/index.md). Keep in mind that different types of mailings require different templates. [Letters](https://docs.postgrid.com/#3359155b-f225-4f6a-b08a-eafe7a52b54d) and [cheques](https://docs.postgrid.com/#ca589be6-1611-414b-9dd9-cbbda752e12c) require one single template while [postcards](https://docs.postgrid.com/#fe8c4cd6-7617-4023-9437-669fa847ccc1) require front and back templates. Similarly, [self mailers](https://docs.postgrid.com/#12c73172-83cf-4e86-945c-8621528c02d2) require inside and outside templates. The same logic for selecting a PDF, existing template, or raw HTML apply when selecting templates for postcards and self mailers. ## Design guidelines You can send four different types of mailing with PostGrid: letters, postcards, cheques and self mailers. Each one of these options have design guidelines that must be followed, including different size options. For letters and cheques, the document size will be determined by the destination country. For postcards, there are three different sizes to choose from (and your chosen templates must follow the same size): - 6x4 - 9x6 - 11x6 For self mailers, we have the following option: - 8.5x11\_bifold Please refer to the [PostGrid documentation](https://docs.postgrid.com/#design) for more information on design guidelines. --- For this demo, we will choose the Create Letters endpoint for our webhook: ![Braze webhook template creation page showing the Create Letters endpoint URL and POST method selected](/_astro/08-image.6E1bXFn3_2imi8a.webp) ## Request headers All requests to the PostGrid API are authorized via an x-api-key header. Retrieve your API key from the dashboard on the [Settings page](https://dashboard.postgrid.com/dashboard/settings) and replace \ with it. - Request headers - Content-Type: application/json - x-api-key: \ ![Braze webhook request headers configuration showing Content-Type and x-api-key header fields](/_astro/04-image.DVGq1uie_ZFk3d2.webp) **Note:** Orders made with your Live API key will be sent to your recipients. It is highly recommended to use your Test API key to ensure everything works as expected before placing live orders. ## Request body Here’s an example request body for **Create Letter** endpoint. In this example, we are using an existing template that contains the merge variable **invoiceNumber**. These properties can change depending on the endpoint you are using. Check PostGrid’s API documentation to see the necessary fields for the endpoint you’d like to use and update your [Liquid fields](https://www.braze.com/docs/user_guide/personalization_and_dynamic_content/liquid) accordingly. ``` { "description": "Braze Webhook test", "to": { "firstName": "{{${first_name}}}", "lastName": "{{${last_name}}}", "addressLine1": "{{custom_attribute.${addressLine1}}}", "addressLine2": "{{custom_attribute.${addressLine2}}}", "city": "{{custom_attribute.${city}}}", "provinceOrState": "{{custom_attribute.${provinceOrState}}}", "postalOrZip": "{{custom_attribute.${postalOrZip}}}", "countryCode": "{{${country}}}" }, "from": "contact_cobebxUxopuz9183dwsD3C", "template": "template_bTZDhA7vx61B3L9CYdVuQX", "mergeVariables": { "invoiceNumber": "{{custom_attribute.${invoiceNumber}}}" }, "color": "true", "addressPlacement": "insert_blank_page", "doubleSided": false } ``` ## Test your request At this point, you should be ready to test your webhook. On the Test tab, you are able to select from a random user, an existing user or create a custom user for the test. Please ensure that your selected user has the necessary custom attributes to send the request. Once this is done, click “Send test” to send your request. A pop-up window containing the response details should be displayed, indicating if your request was successful and displaying any error messages if applicable. You can also check your newly created order or API logs on PostGrid’s dashboard. ![Braze webhook test response pop-up showing a successful request with a 200 OK status](/_astro/05-image.Czbqi5Xa_1NBpQF.webp) ## Common errors ### 401 Unauthorized This error message can appear due to a missing or incorrect API key. Make sure that you set the x-api-key header and that your API key is correct. ### 400 Bad Request This error may indicate that your request payload is formatted incorrectly. Remember that your request headers and body need to follow JSON formatting. It is also possible that your request body is missing a parameter required by PostGrid. In this case, check the webhook response for more information on the error and refer to [PostGrid’s API documentation](https://docs.postgrid.com/) for details on the expected parameters. ![Braze webhook test response showing a 400 Bad Request error with a missing required field message](/_astro/06-image.6tn2jRGO_Z2sxeX7.webp) ## Use webhook in a campaign or Canvas Your webhook is now ready to be used in a Braze campaign or Canvas. Braze allows webhooks to be delivered on a scheduled time, an action of your choice or based on an API trigger. For instance, you can choose to deliver the webhook everytime a change is made to a specific custom attribute: ![Braze campaign delivery settings showing a trigger configured to fire when a custom attribute changes](/_astro/07-image.B3AZ7d4F_jVs85.webp) There are many other triggers available to choose from. Please refer to the [Braze documentation](https://www.braze.com/docs/user_guide/message_building_by_channel/webhooks/creating_a_webhook#step-5-build-the-remainder-of-your-campaign-or-canvas) for more information on scheduling a webhook delivery or trigger. ## PDF Previews We provide PDF previews for all orders, including those created in test mode. These previews should be available a few seconds after you create an order. You can access them on the dashboard by clicking View PDF on the top-right of the order details page. Alternatively, you can use the [Get Letter](https://docs.postgrid.com/#ab066af8-1a0d-483a-889b-2263f1c6c0a4) endpoint to retrieve the created letter and use the url property to view the generated PDF. For cheques, the previews will censor the account number by padding the last 4 digits with zeros. ## Tracking your order PostGrid can provide the exact status of an order as reported by the underlying mail carrier, but this feature is only available when an appropriate mailingClass is used (e.g., USPS certified mail). You can learn more about this feature [here](/api/index.md).