Practical examples of using the Boldem API

Michal Krejčí

16. October 2023

This document contains practical examples you can use when implementing the API for the Boldem marketing automation tool.

Complete documentation for all endpoints is available at https://api.boldem.cz/.

Boldem API Authorization

You can find the authorization (verification) procedure for the Boldem API, including examples, in the dedicated chapter.

Prerequisites for using the Boldem API

To ensure the examples work correctly, you must meet a few requirements.

Create a Boldem account and subscribe to the E-mailing plan.
Add a sending domain to your account and verify it – instructions for setting up sending domains for various providers.
Some endpoints assume mailing lists already exist. Working with mailing lists is not covered in this document; it is straightforward API work according to the documentation.

We also assume that for multiple accounts one domain router per account — and therefore one specific domain router ID — will be sufficient. In the examples below we therefore use the specific dispatcherId = 44. In other cases, request the dispatcherId from customer support.

In the response body of Create and Update requests you will always receive the complete object of the given resource.

If processed successfully, you will receive one of the 2xx status codes (depending on the operation).

If there is a problem processing the request, an error code is returned and the issue is described in the response body.

For some endpoints, the correct combination of values is important, so to make things as simple as possible we provide concrete examples of requests.

Create a template for a bulk email campaign

Endpoint

POST /v1/html-templates

Data section

{
    "dispatcherId": null,
    "templateGroupId": null,
    "name": "Save the Date Template",
    "subject": "Subject of Save the Date Template",
    "preheader": "Preheader of Save the Date Template",
    "body": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"> <title></title> </head><body><h1>Header</h1> <p>Some content</p></body></html>",
    "bodyAlternative": "Header\r\nSomeContent",
    "isTransactional": false,
    "trackClicks": true,
    "trackOpens": true,
    "fromAddress": null,
    "fromDisplayName": null,
    "webTrackParam": null,
    "replyToAddress": null
}

Response code on success

201

Notes

The parameter isTransactional must be set to false. This indicates that it is a template for bulk deliveries.

If the request is processed successfully, the template is available for review in the Boldem app interface under the Templates section.

The templateId parameter in the response body contains the identifier of the newly created template for further use.

Create a bulk email campaign and assign mailing lists

Endpoint

POST /v1/mass-email-campaigns

Data section

{
    "templateId": 3033, // templateId from the previous call
    "dispatcherId": 44, // specific dispatcherId
    "name": "Save the Date Campaign",
    "description": "Description of Save the Date Campaign",
    "webTrackParam": null,
    "fromAddress": "info@example.com",
    "fromDisplayName": "YOUR COMPANY NAME",
    "replyToAddress": null,
    "trackClicks": true,
    "trackOpens": true,
    "mailingListIds": [125] // specific mailing list IDs from the system
}

Success response code

201

Notes

If the request is processed successfully, the template is available for review in the Boldem application in the Campaigns section.

In the response body, the campaignId parameter contains the identifier of the newly created template for further use.

Recipients unsubscribed from the campaign

The example call below removes the selected recipient from the specified campaign.

Endpoint

POST /v1/unsubscribes

Data section

{
    "email": "user@example.com",
    "mailingListId": null,
    "campaignId": 1175, // campaignId from the previous step (ID of the bulk campaign we don't want to send to this recipient
    "validFrom": null,
    "validTo": null
}

Success response code

201

Notes

If processed successfully, you can find an entry for that email and campaign in the Boldem app under Mailing lists > Unsubscribed recipients.
If you don’t want to unsubscribe the recipient globally but only from a specific campaign, you must provide the campaignId parameter. If campaignId remains null, the recipient will be unsubscribed from all deliveries in the account.

Send test delivery

Endpoint

POST /v1/mass-email-campaign-tests

Data section

{
    "email": "user@example.com",
    "campaignId": 1175
}

Success status code

202

Notes

Test delivery is performed by dispatching a transactional email with the specified campaign to the specified recipient. It is an asynchronous operation. In the response header, the Location parameter contains the endpoint address to retrieve the status of the transactional email dispatch (GET /v1/{{LocationHeaderContent}}).

If processing is successful, you can find information about that transactional email in the Boldem app interface in the Transactional emails section.

Execute live bulk deliveries

Endpoint

POST /v1/mass-email-campaign-executions

Data section

{
    "campaignId": 1175
}

Success status code

202

Notes

Before dispatch, the delivery settings are validated. For successful dispatch, a sending domain and domain router must be configured, and the template must include an unsubscribe link.
This is an asynchronous operation. The response header contains the endpoint address in the Location parameter for retrieving the status of a bulk delivery dispatch (GET /v1/{{LocationHeaderContent}}). The address also includes the delivery ID (campaign-execution-states/{{campaignExecutionId}}).

After successful processing, you can find the campaign’s delivery status and statistics in the Boldem app under Campaigns.

Check status of bulk deliveries

Endpoint

GET /v1/campaign-execution-states/{{campaignExecutionId}}

Success status code

200

Notes

The response body includes information about the state and phase of the delivery. Text values are described in the documentation (CampaignExecutionStateApi, CampaignExecutionPhaseApi). A successful dispatch of a complete delivery is represented by the combination state = 1 and phase = 4. For example:

{
    "campaignId": 1175,
    "state": 1, // Active
    "phase": 4 // Finished
}

Bulk deliveries statistics

Generate statistics for bulk deliveries in .csv format.

Endpoint

GET /v1/mass-email-campaigns/{{campaignId}}

Success status code

200

In the response body, you’ll find the stats parameter, which contains statistical data about the campaign’s deliveries.

You can also enable statistics in the bulk campaigns list by using the include parameter.

Endpoint

GET /v1/mass-email-campaigns?include=stats

Success status code

200

Compared to a call without the include parameter, the response text will include a stats attribute for each object in the list that contains the campaign’s delivery statistics.

Creating a campaign for transactional deliveries

Endpoint

POST /v1/html-templates

Data section

{
    "dispatcherId": 44,
    "templateGroupId": null,
    "name": "Transactional Template",
    "subject": "Subject of Transactional Template",
    "preheader": "Preheader of Transactional Template",
    "body": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"> <title></title> </head><body><h1>Header</h1> <p>Some content</p></body></html>",
    "bodyAlternative": "Header\r\nSomeContent",
    "isTransactional": true,
    "trackClicks": true,
    "trackOpens": true,
    "fromAddress": "info@example.com",
    "fromDisplayName": "YOUR COMPANY NAME",
    "webTrackParam": null,
    "replyToAddress": null
}

Success response code

201

Notes

The parameter isTransactional must be set to true. This indicates the template is for transactional emails. To use a transactional template, you must have the parameters dispatcherId, trackClicks, trackOpens, fromAddress and fromDisplayName set.

If the request is processed successfully, the template is available for review in the Boldem app interface under the Templates section.

The parameter templateId in the response body contains the identifier of the newly created template for further use.

Transactional email dispatch

Endpoint

POST /v1/transactional-emails

Data section

{
    "to": {
        "address": "user@example.com"
    },
    "templateId": 3035,
    "variables": {
        "surname": "Novák",
        "name": "Jan",
        "sex": true,
        "age": 30,
        "actionDate": "2021-08-13"
    }
}

Success status code

202

Notes

Dispatch of a transactional email is only possible with a transactional template (isTransactional = 1).
This is an asynchronous operation. The response header contains the endpoint address in the Location parameter for getting the status of the transactional email dispatch (GET /v1/{{LocationHeaderContent}}).
If processing is successful, you can find information about that transactional email in the Boldem app interface in the Transactional emails section.