Examples of Boldem API usage

Michal Michal Krejčí
16. October 2023

In this document, you will find practical examples for implementing the Boldem automated marketing tool API.

Complete documentation for all endpoints can be found at https://api.boldem.cz/.

Authorization to Boldem API

The procedure for authorization (authentication) to the Boldem API, including examples, can be found in a separate chapter.

Prerequisites for using Boldem API

For the examples to work properly, several requirements need to be met.

  • Create a Boldem account and subscribe to the Profi plan.
  • Add a sending domain to your account and verify it – setting up sending domains with different providers.
  • With certain endpoints, we assume that mailing lists have already been created. However, working with mailing lists is not covered in this guide. It is easy to do so by following this article.

We also assume that when dealing with multiple accounts, a single domain router and one specific domain router ID will suffice for each account. Therefore, in the following examples, we will use the specific dispatcherId = 44. Please contact customer support to receive your dispatcherId.

In response to Create and Update requests, you will always receive the complete resource object in the response body.

If processing is successful, you will receive an HTTP status code in the 2xx range (depending on the type of operation).

If there are issues processing the request, an error code is displayed, and the problem is described in the response body.

For some endpoints, achieving the correct combination of values is essential. Therefore, we provide specific examples of calls to ensure maximum simplicity.

Creating template for bulk email campaign

Endpoint

POST /v1/html-templates

Data part

{
    "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
}

Success response code

201

Notes

  • The isTransactional parameter must be set to false. By doing that, we set the template for bulk delivery.
  • If the request processing is successful, you can review the template in the Boldem interface under Templates.
  • The response body contains the identifier of the newly created template for further work in the templateId parameter.

Creating bulk email campaign with mailing list assignment

Endpoint

POST /v1/mass-email-campaigns

Data part

{
    "templateId": 3033, // templateId from 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 recipient list IDs from the system
}

Success response code

201

Notes

  • If the request processing is successful, you can review the template in the Boldem interface under Campaigns.
  • The response body contains the identifier of the newly created template for further work in the campaignId parameter.

Unsubscribing recipients from campaign

The example call below excludes the selected recipient from the selected campaign.

Endpoint

POST /v1/unsubscribes

Data part

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

Success response code

201

Notes

  • If processing is successful, you can find an entry in the Boldem interface for the given email and campaign under the Mailing lists > Unsubscribed recipients section.
  • If you wish not to unsubscribe the recipient globally but only from a specific campaign, you must provide a value for the campaignId parameter. If the campaignId parameter is left null, the recipient will be unsubscribed from all deliveries in the account.

Executing test email deliveries

Endpoint

POST /v1/mass-email-campaign-tests

Data part

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

Success status code

202

Notes

  • Test email delivery involves sending a transactional email to a specific recipient as part of a given campaign. This operation is asynchronous. To check the dispatch status of the transactional email, you can locate the endpoint address in the response header under the Location parameter (GET /v1/{{LocationHeaderContent}}).
  • If processing is successful, information for the transaction email can be found in the Boldem interface in the Transactional emails section.

Executing bulk email deliveries

Endpoint

POST /v1/mass-email-campaign-executions

Data part

{
    "campaignId": 1175
}

Success status code

202

Notes

  • Prior to the actual dispatch, the delivery settings are validated. To ensure a successful delivery, you must have the sending domain and router configured, as well as include a logout link in the template.
  • This is an asynchronous operation. In the response header, the Location parameter contains the endpoint address for retrieving bulk delivery status information (GET /v1/{{LocationHeaderContent}}). The address also includes the delivery ID (campaign-execution-states/{{campaignExecutionId}}).
  • If processing is successful, information about the status of the campaign’s deliveries and its statistics can be found in the Campaigns section of the Boldem app.

Checking status of bulk delivery

Endpoint

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

Success status code

200

Notes

The response body includes information about the status and stage of the delivery. The text values are described here (CampaignExecutionStateApi, CampaignExecutionPhaseApi). Successful dispatch of a complete delivery is represented by a combination of state = 1 and phase = 4. For example: 

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

Bulk delivery statistics

Generating bulk delivery statistics in .csv format.

Endpoint

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

Success status code

200

In the response body, you will find the statsparameter, which contains statistical data about the campaign’s deliveries.

You can also “enable” statistics for the bulk campaign listing 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 stats attribute will be included in the response text for each object in the listing. This attribute contains campaign delivery distribution statistics.

Creating campaign for transactional delivery

Endpoint

POST /v1/html-templates

Data part

{
    "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 isTransactional parameter must be set to true. By doing that, we set a template for transactional emails. To use the template, the parameters dispatcherId, trackClicks, trackOpens, fromAddress , and fromDisplayNamemust be set.
  • If the request processing is successful, you can review the template in the Boldem interface under Templates.
  • The response body contains the identifier of the newly created template for further work in the templateId parameter.

Sending transactional email

Endpoint

POST /v1/transactional-emails

Data part

{
    "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

  • Sending a transactional email is only possible with a transactional template (isTransactional = 1).
  • This operation is asynchronous. To check the dispatch status of the transactional email, you can locate the endpoint address in the response header under the Location parameter (GET /v1/{{LocationHeaderContent}}).
  • If processing is successful, information for the transaction email can be found in the Boldem interface in the Transactional emails section.