Comment on page
Braze
This integration will allow customers to send data from Braze to Lob. This webhook can then be used within a campaign to send mail to customers. After sending through braze, the mail data can be accessed from within the Lob dashboard.
Add Custom Attributes for user mailing address information:
address_line1
address_line2
address_city
address_state
address_zip
address_country

Update user profiles with mailing addresses.

Anything highlighted is a custom variable that will need to be updated for each customer or use case.
curl -X POST \
https://rest.iad-01.braze.com/users/track \
-H 'Content-Type: application/json' \
-d '{
"api_key": "Braze_API_Key",
"attributes": [
{
"external_id" : "10142019",
"address_line1" : "185 BERRY ST STE 6100",
"address_line2" : null,
"address_city" : "SAN FRANCISCO",
"address_state" : "CA",
"address_zip" : "94107-1741",
"address_country" : "UNITED STATES"
}
]
}'

Create a webhook template (Braze Documentation). Once this template is made it can be used for your future campaigns as well. In the case that you have different variations of sends, meaning you are going to perform one send with postcards and one with letters it is recommended that you create 2 separate webhook templates in Braze for this.
Additionally, if you are going to be doing small variations such as sending first-class vs standard class depending on the recipient, then you can leverage Braze's conditional logic. You can build this logic into the template and have one webhook template support multiple variations.
Compose tab:
Webhook URL:
https://api.lob.com/v1/postcards
Request body: Raw Text
Braze's default webhook template does not include the opening and closing
{}
brackets, so ensure those have been added before saving.{
"description" : "{{campaign.${name}}}",
"metadata" : {
"campaign" : "{{campaign.${name}}}"
},
"to" : {
"name" : "{{${first_name}}} {{${last_name}}}",
"address_line1" : "{{custom_attribute.${address_line1}}}",
"address_line2" : "{{custom_attribute.${address_line2}}}",
"address_city" : "{{custom_attribute.${address_city}}}",
"address_state" : "{{custom_attribute.${address_state}}}",
"address_zip" : "{{custom_attribute.${address_zip}}}"
},
"from" : "adr_2066448bdef840f1",
"front" : "tmpl_8b3b1249ede0406",
"back" : "tmpl_d69077c7be7bd09",
"merge_variables" : {
"name" : "{{${first_name}}}"
}
}
Compose tab:
Webhook URL:
https://api.lob.com/v1/letters
Request body: Raw Text
{
"description" : "{{campaign.${name}}}",
"to" : {
"name" : "{{${first_name}}} {{${last_name}}}",
"address_line1" : "{{custom_attribute.${address_line1}}}",
"address_line2" : "{{custom_attribute.${address_line2}}}",
"address_city" : "{{custom_attribute.${address_city}}}",
"address_state" : "{{custom_attribute.${address_state}}}",
"address_zip" : "{{custom_attribute.${address_zip}}}"
},
"from" : "adr_2066448bdef840f1",
"file" : "tmpl_d69077c7be7bd09",
"color" : "true",
"merge_variables" : {
"name" : "{{${first_name}}}"
},
"metadata" :
"campaign" : "{{campaign.${name}}}",
"zip" : "{{custom_attribute.${address_zip}}}"
},
"mail_type" : "usps_first_class",
"double_sided": false,
"address_placement": "top_first_page",
"mail_type": "usps_first_class",
"return_envelope": true,
"perforated_page": 1,
"extra_service": "registered",
"custom_envelope": null,
"billing_group_id" : ""
}
Compose tab:
Webhook URL:
https://api.lob.com/v1/self_mailers
Request body: Raw Text
{
"description" : "{{campaign.${name}}}",
"size" : "6x18_bifold",
"to" : {
"name" : "{{${first_name}}} {{${last_name}}}",
"address_line1" : "{{custom_attribute.${address_line1}}}",
"address_line2" : "{{custom_attribute.${address_line2}}}",
"address_city" : "{{custom_attribute.${address_city}}}",
"address_state" : "{{custom_attribute.${address_state}}}",
"address_zip" : "{{custom_attribute.${address_zip}}}"
},
"from" : "adr_2066448bdef840f1",
"inside" : "tmpl_8b3b1249ede0406",
"outside" : "tmpl_d69077c7be7bd09",
"merge_variables" : {
"name" : "{{${first_name}}}"
},
"metadata" :
"campaign" : "{{campaign.${name}}}",
"zip" : "{{custom_attribute.${address_zip}}}"
},
"mail_type" : "usps_first_class",
"billing_group_id" : ""
}
Be sure to leave the
:
after the Lob API key you paste in between the apostrophes.REQUEST HEADERS:
- Authorization: Basic
{{ 'YOUR_LOB_API_KEY:' | base64_encode }}
- Content-Type:
application/json
- Idempotency-Key:
{{${user_id}}}
- It is recommended that you leverage idempotency keys to prevent duplication of mail being sent. It can be any value you seem fit but often it is userID or a combination of userID and campaign name.
- HTTP METHOD:
POST
Test your new webhook template and check your Lob dashboard to ensure desired results. It is recommended to run a one-off test in Braze to see if the request format is set up appropriately and then run a full end-to-end test where you send an entire campaign through your test environment.
When running a one-off test it is useful to have test users in your system who have the correct data needed to send mail and validate your creatives. Here is an example of a test we would perform.
- 1.401 Unauthorized
- If you receive this error message, your API key is incorrect.
- Make sure you have the header
Authorization
and that you are encoding your secret API key with a colon after the key like thisBasic {{ 'YOUR_LOB_API_KEY:' | base64_encode }}
- 2.422 Unprocessable Entity (Invalid request payload JSON format)
- If you receive this error, it is likely that your payload is not formatted correctly. It needs to match JSON formatting.
- Generally speaking, the rules that are often broken are:
- 1.All keys and values are enclosed in double quotes (
"
). - 2.Commas after every key-value pair except for the last one.
- 3.No newline characters in any values and no extra spaces between fields.
- 3.422 Unprocessable Entity (Other)
- Other than JSON errors, you can receive
422
errors in the payload sent to Lob does not match our requirements. - For example, if you are missing
address_line1
in the payload you will get an error saying that is needed. For these errors, you can make the appropriate adjustments and retry your requests.
The "testing" functionality in Braze is sending a one-off request to Lob, this means if you have your LIVE API key in the template it will create mail and if you have your test key it will not.
Make sure when you are testing that your cancellation windows are set to an ample time (2 hours is recommended) to make sure you can always cancel mail if you make a mistake.
To leverage merge variables, in Braze you will reference the merge variable in your HTML file as the Key and the user attribute as the value.
For example, if you had a merge variable called
f_name
in your HTML, then in the section of your payload called merge_variables
you would have a key of f_name
and a value of the user attribute in Braze. Here is an example of what that would look like in Braze "merge_variables" : {
"f_name" : "{{${first_name}}}"
}
Essentially you can either host your HTML in the Lob platform where you can then reference the template ID that is created for you, or you can leverage Braze’s Media Library where you will be provided with a URL that can be used as the value for these parameters.
Here is an example of what you could see in Braze:
"file" : "tmpl_3v234vl23hj5v"
"file" : "https://braze-images.com/appboy/communication/assets/image_assets/images/25660da30cdc28a314/original.jpg?1637006884"
- By default, all accounts and their corresponding Test and Live API Keys have a rate limit of 150 requests per 5 seconds per endpoint
Last modified 4mo ago