Blackleaf API Developer Guide: Templates, SMS, Webhooks, Contacts and Automations

Quick answer

The Blackleaf API is a REST API for messaging, contacts, campaigns, automations, sender profiles, 2FA, account data, and reporting. Production requests use the base URL https://api.blackleaf.io, Bearer authentication, JSON request bodies, and JSON responses.

Use the interactive Blackleaf API documentation as the current endpoint reference. This guide explains how the pieces should be used together in a production integration.

Choose the correct Blackleaf messaging workflow

Not every message should be implemented as a direct API send. Start by identifying the operational model.

Authenticate with a Bearer token

Every documented API operation requires an Authorization header containing a Bearer token.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Keep the token in a server-side secret manager or protected environment variable. Do not place it in browser JavaScript, a mobile application bundle, a public repository, logs, screenshots, support tickets, or customer-visible error messages.

A safe first request is the account-balance endpoint because it verifies the production base URL and token without creating a contact or sending a message.

curl --request GET \
  --url "https://api.blackleaf.io/account/balance" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Accept: application/json"

const response = await fetch("https://api.blackleaf.io/account/balance", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.BLACKLEAF_API_KEY}`,
    Accept: "application/json"
  }
});

const result = await response.json();

if (!response.ok) {
  throw new Error(`Blackleaf request failed with HTTP ${response.status}`);
}

console.log(result.balance);

Step 1: Create the message template

Create a template with POST /messaging/create/template. The request can include a message body, an optional image, and unsubscribeText.

The template body may contain supported placeholders. The API documentation uses {{firstName}} and {{url}} as examples.

curl --request POST \
  --url "https://api.blackleaf.io/messaging/create/template" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "body": "Example Store: Hi {{firstName}}, your order is ready. View details: {{url}}",
    "unsubscribeText": "Reply STOP to end"
  }'

A successful template response includes fields such as:

{
  "id": "TEMPLATE_ID",
  "accepted": true,
  "bodyAccepted": true,
  "imageAccepted": true,
  "status": "accepted",
  "explanation": "Your template has been accepted."
}

Do not treat an HTTP 200 response by itself as proof that the template is ready. Check accepted, bodyAccepted, imageAccepted, status, and explanation. A template may be created while some or all of its content is not accepted for sending.

The public API reference does not currently document an idempotency key for template creation. Prevent accidental duplicates by recording your own logical template name, version, content hash, returned ID, status, and creation time.

Step 2: Send the accepted template

Send an SMS or MMS with POST /messaging/send/text. For the normal production workflow, provide the recipient in to, the approved template ID in templateId, and any data needed to resolve the template placeholders.

curl --request POST \
  --url "https://api.blackleaf.io/messaging/send/text" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+15551234567",
    "templateId": "TEMPLATE_ID",
    "contact": {
      "firstName": "Jordan",
      "lastName": "Lee"
    },
    "landingUrl": "https://example.com/orders/12345",
    "sendingProfileId": "SENDER_PROFILE_ID"
  }'

async function sendOrderReadyText({ phone, firstName, orderUrl }) {
  const response = await fetch(
    "https://api.blackleaf.io/messaging/send/text",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.BLACKLEAF_API_KEY}`,
        "Content-Type": "application/json",
        Accept: "application/json"
      },
      body: JSON.stringify({
        to: phone,
        templateId: process.env.BLACKLEAF_ORDER_READY_TEMPLATE_ID,
        contact: { firstName },
        landingUrl: orderUrl,
        sendingProfileId: process.env.BLACKLEAF_SENDER_PROFILE_ID
      })
    }
  );

  const raw = await response.text();
  let result;

  try {
    result = raw ? JSON.parse(raw) : {};
  } catch {
    result = { raw };
  }

  if (!response.ok) {
    const error = new Error(`Blackleaf send failed with HTTP ${response.status}`);
    error.status = response.status;
    error.details = result;
    throw error;
  }

  return result;
}

The send response includes an id and a status. Store the message ID with the business event that caused the send, such as the order ID, customer ID, notification type, and timestamp.

Fields supported by the send endpoint

The live API reference documents the following request fields for POST /messaging/send/text.

Only send fields your integration actually uses. Treat the interactive API documentation and the configuration of the specific Blackleaf account as the source of truth for supported placeholders, landing experiences, sender profiles, and age-aware behavior.

Why templates should be the default

Blackleaf evaluates message content because regulated and carrier-sensitive messaging cannot be treated as an unrestricted pipe. Templates make that review reusable.

If a customer asks whether raw message bodies are supported, the practical answer is yes for content that must be created dynamically, but templates are the preferred path whenever the structure can be known in advance.

Select a sender profile

A sender profile represents the Blackleaf sending configuration used to route a message. Retrieve available profiles with GET /messaging/senders/profiles.

curl --request GET \
  --url "https://api.blackleaf.io/messaging/senders/profiles?pageSize=100&page=0" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Accept: application/json"

The response is paginated and contains an items array. Each documented profile includes fields such as _id, title, healthy, sticky, dateCreated, and dateModified.

Store the selected profile’s _id and pass it as sendingProfileId when the application must choose a specific profile. Do not hard-code an ID copied from another Blackleaf organization or environment.

Create, update, retrieve, subscribe, and unsubscribe contacts

Blackleaf provides contact endpoints for synchronizing customer identity, profile, subscription status, and rewards data.

Upsert a contact

curl --request POST \
  --url "https://api.blackleaf.io/contact/set" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customerId": "customer_12345",
    "phone": "+15551234567",
    "email": "jordan@example.com",
    "firstName": "Jordan",
    "lastName": "Lee",
    "dob": "1990-05-20T00:00:00.000",
    "consumerType": "AdultUse"
  }'

The contact upsert endpoint can identify and update a contact by phone number, email, or customer ID. Use a stable customerId from the source system whenever one exists, and normalize phone numbers before synchronization.

When a customer opts out, process the change immediately and synchronize it back to every system that can initiate a send. Review Blackleaf’s SMS opt-in and consent guide and dispensary SMS compliance framework before launching production marketing traffic.

Invoke and manage campaigns through the API

Use a campaign when Blackleaf should manage one message across a defined audience. The API supports listing, creating or modifying, starting, pausing, and canceling campaigns.

For most integrations, the safest path is to configure and review the campaign in Blackleaf, retain its campaign ID, and invoke the resulting endpoint from the external system.

curl --request POST \
  --url "https://api.blackleaf.io/campaign/CAMPAIGN_ID/send/" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Accept: application/json"

The documented response contains a status such as Started. Starting a campaign is an operational action, so protect the endpoint with application authorization, prevent duplicate operator actions, log the initiating user or event, and verify the campaign’s audience and state before invoking it.

If the application needs to build campaigns entirely through the API, follow the current campaign schema in the interactive documentation. Campaign configuration contains significantly more state than a single-message send and should not be reduced to a guessed minimal payload.

Invoke an automation from a POS, ecommerce platform, or backend

Use POST /automation/{_id}/invoke/ when an external event should enter a workflow already configured in Blackleaf. The request contains a contact object and an optional payload object.

curl --request POST \
  --url "https://api.blackleaf.io/automation/AUTOMATION_ID/invoke/" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "contact": {
      "customerId": "customer_12345",
      "phone": "+15551234567",
      "firstName": "Jordan",
      "lastName": "Lee"
    },
    "payload": {
      "eventId": "order_98765_ready",
      "orderId": "98765",
      "status": "Ready for Pickup"
    }
  }'

The documented success response contains {"status":"Started"}.

Include a stable event identifier in the payload even when the current workflow does not display it. Your application can use that value to prevent the same source event from invoking the automation twice and to trace a customer question back to the originating system.

Send and verify two-factor authentication codes

Blackleaf provides dedicated endpoints for one-time security codes. Do not build 2FA by generating a code and inserting it into a marketing-message template.

Send a code

curl --request POST \
  --url "https://api.blackleaf.io/messaging/send/2fa" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone": "+15551234567",
    "digits": 6,
    "expires": 300
  }'

Verify a submitted code

curl --request POST \
  --url "https://api.blackleaf.io/messaging/verify/2fa" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone": "+15551234567",
    "code": 123456
  }'

The send endpoint documents phone, digits, and expires. The verification endpoint requires the phone number and submitted code. Apply application-level controls for repeated requests, failed attempts, session binding, and abuse prevention.

Retrieve messages and synchronize records

Use GET /messaging/messages to retrieve message records. The endpoint supports:

• campaignId to filter messages associated with a campaign
• pageSize from 1 to 1,000
• page, beginning with page 0
• lastModified as a UTC ISO 8601 timestamp
• sort as asc or desc

curl --request GET \
  --url "https://api.blackleaf.io/messaging/messages?pageSize=100&page=0&sort=asc&lastModified=2026-08-01T00%3A00%3A00Z" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Accept: application/json"

Paginated list responses contain items, page, pageSize, totalItems, and hasMoreItems. Continue requesting the next page until hasMoreItems is false.

A message record may contain the message ID, destination, source number, template ID, body, image, campaign context, sender profile, carrier, delivery status, message type, number of parts, cost, and created or modified timestamps.

Process message-status and inbound-message webhooks

Polling is useful for reconciliation, but webhooks are the preferred way to receive real-time delivery changes and customer replies.

Message-status webhook

A message-status webhook is sent when delivery status changes. The documented payload can include:

{
  "org": "org_12345",
  "messageId": "a1b2c3d4e5",
  "dateModifiedLong": 1759935198703,
  "status": "delivered",
  "carrier": "Verizon",
  "from": "+15551234567",
  "to": "+15559876543",
  "errorData": {
    "code": "30007",
    "description": "Carrier filtering"
  }
}

Use messageId to correlate the event with the ID returned by the original send request. The errorData object is included when the carrier reports a failure or filtering issue.

Inbound-message webhook

An inbound webhook is sent when a recipient replies. The documented payload can include:

{
  "to": "+15551234567",
  "from": "+15559876543",
  "org": "org_12345",
  "body": "Is my order ready?",
  "messageId": "d3e4f5g6h7",
  "type": "inbound",
  "dateCreated": "2026-08-18T18:20:00.000Z"
}

Acknowledge a valid webhook with 200 OK. The documentation notes that failing to acknowledge an inbound event may result in retries or duplicate delivery.

The public documentation describes the webhook payloads but does not publish one universal webhook-secret format or configuration endpoint. Use the webhook setup and verification method supplied for the specific Blackleaf account rather than inventing a signature header.

Blackleaf API endpoint map

The current API documentation groups operations into messaging, automations, campaigns, contacts, products, orders, account data, and analytics.

Use the exact path shown in the live API reference. Several endpoints intentionally include a trailing slash. Do not assume that a different path, method, or legacy query-string version is equivalent.

How to design a production Blackleaf integration

1. Separate configuration from runtime data

Store API tokens, template IDs, automation IDs, campaign IDs, and sender profile IDs as protected configuration. Pass customer, order, link, and event values at runtime.

2. Create an application-side message key

Before calling Blackleaf, assign the business event a stable key such as order_98765_ready_v1. Record the event key, recipient, template ID, request time, Blackleaf message ID, initial status, and final delivery state.

3. Prevent duplicate sends before making the request

The public API reference does not document a client-supplied idempotency header for message sends. Enforce uniqueness in your own database before sending. A unique constraint on the source event and notification type is stronger than an in-memory flag.

4. Do not blindly retry an uncertain send

If the connection times out after the request leaves your server, the message may already have been accepted. A blind retry can produce a duplicate. Mark the attempt as uncertain, reconcile against message records where possible, and use a controlled recovery process.

5. Treat delivery as asynchronous state

Model message state separately from the HTTP request. Store the initial response, update the record from webhooks, and reconcile through GET /messaging/messages.

6. Normalize identity consistently

Use one phone-number normalization strategy across contacts, sends, orders, webhook matching, suppression, and customer support. Prefer E.164 storage, and do not create a second customer record merely because punctuation differs.

7. Keep suppression in the critical path

Before initiating a marketing send, verify that the customer is eligible for the specific use case. When an opt-out occurs, update Blackleaf and every external system that can trigger a message.

8. Monitor by template, sender, carrier, and workflow

Aggregate accepted, delivered, failed, filtered, and inbound events by template ID, sender profile, carrier, campaign, automation, and source event. A single account-wide delivery rate can hide a failing integration path.

Error handling and troubleshooting

Blackleaf uses standard HTTP response codes, but integration logic should preserve the response body because it may contain the most useful explanation.

When asking Blackleaf support to investigate, provide the organization, endpoint, approximate UTC time, Blackleaf message or object ID, HTTP status, sanitized response body, and the expected result. Do not send the API token or unnecessary customer data.

Production launch checklist

Information needed to answer an API support question

Most integration questions can be answered quickly when the request includes the following details:

1. The exact endpoint and HTTP method
2. Whether the request uses production, test, or development
3. The approximate request time in UTC
4. The HTTP response status
5. The sanitized response body
6. The Blackleaf template, message, campaign, automation, or contact ID involved
7. The expected behavior and the actual behavior
8. Whether the issue happens consistently or only for certain recipients, carriers, templates, or sender profiles
9. Whether a message-status or inbound webhook was received
10. Whether retry logic may have run

Replace the API token and sensitive customer content before sharing an example. A useful sanitized request preserves field names, data types, endpoint paths, IDs relevant to the investigation, timestamps, and response details.

When an API question should be escalated

The documentation can answer how to authenticate, which endpoint to call, why templates are preferred, which fields are documented, how pagination works, and how delivery or inbound events are reported. Some questions depend on account configuration or platform-side data and should not be answered by guessing.

Blackleaf API frequently asked questions

Sources and further reading

• Blackleaf API documentation
• Blackleaf dispensary SMS integrations
• POS-integrated vs. POS-agnostic dispensary text messaging
• Cannabis SMS compliance for dispensaries
• Opt-in and consent for dispensary SMS
• 10DLC registration for dispensaries
• API access for campaigns and automations