Blackleaf Messaging API Sandbox: SMS, MMS and 2FA Testing

Choose the sandbox base URL first

Use normal workspace Bearer authentication from your backend. Keep the API key out of browser code, public repositories, screenshots and support examples.

API_BASE="https://api-sandbox.blackleaf.io"

Authorization: Bearer YOUR_WORKSPACE_API_KEY
Content-Type: application/json

The base URL selects the messaging environment. Adding sandbox: true or environment: "sandbox" to a request sent to https://api.blackleaf.io does not turn that production request into a simulation. api-test.blackleaf.io is not one of the two documented sandbox aliases.

This is a messaging sandbox, rather than a promise of an isolated copy of every API resource. Do not assume campaign launches, automations or unrelated write endpoints become simulated merely because you use a sandbox hostname.

Rehearse a template and an SMS or MMS

Create a template on the sandbox host, retain its returned id, then use that ID in a sandbox send. These examples use a fictional North American phone number. They are request examples to review, not a record of a completed test.

curl --request POST \
  --url "$API_BASE/messaging/create/template" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "body": "Example Store: Your sample order is ready.",
    "unsubscribeText": "Reply STOP to end",
    "simulateAi": false
  }'

With simulateAi: false, validation is simulated. A simulated accepted template is test data, not production content approval. Review the returned acceptance fields and any explanation before continuing.

curl --request POST \
  --url "$API_BASE/messaging/send/text" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "2025550101",
    "templateId": "YOUR_SANDBOX_TEMPLATE_ID",
    "simulateAi": false
  }'

Replace YOUR_SANDBOX_TEMPLATE_ID with the ID returned by your sandbox template request. Inspect the response for success or errors and retain the message identifier for the result check.

Include an image for the MMS rehearsal

To rehearse MMS, create a separate sandbox template with its image field pointing to an accessible test image you are authorized to use. Review its body and image acceptance fields, then send using that template’s returned ID. Check the prepared image, personalization and landing content your application actually needs.

A successful simulation can confirm that the message was prepared in that test flow. It does not prove that a carrier accepted the image, that a handset displayed it or that the production content has been approved.

Test 2FA verification without a handset

Use the dedicated /messaging/send/2fa and /messaging/verify/2fa paths for a signup or password-reset integration. This workflow does not require creating a text template. It is separate from signing into the Blackleaf dashboard.

curl --request POST \
  --url "$API_BASE/messaging/send/2fa" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone": "2025550101",
    "digits": 6,
    "expires": 300
  }'

Successful sandbox issuance returns the generated code, sessionId, expiresIn and messageId, with environment: "sandbox" and simulated: true. The code is available in that response; receiving a real SMS or looking up the message list is not required to continue. Production issuance does not return the code.

Send the returned code to the verification path using the same phone, workspace and sandbox environment. The value 123456 below is fictional; replace it with the code from your own permitted sandbox request.

curl --request POST \
  --url "$API_BASE/messaging/verify/2fa" \
  --header "Authorization: Bearer $BLACKLEAF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone": "2025550101",
    "code": 123456
  }'

A successful verification returns verified: true and the issuance session ID. A wrong or expired code returns verified: false with error: "Invalid code or expired". Sandbox codes cannot verify a production request or a request in another workspace.

Pending verification state is temporary. Verification must reach the same API process that issued the challenge; a restart clears pending codes. Reissuing replaces the matching phone/workspace/environment challenge. Plan the application’s test flow around that behavior rather than treating every failed verification as an SMS delivery problem.

Sandbox 2FA sends no real SMS and has no delivery fee. It performs no AI validation, so it has no AI charge and simulateAi has no effect on this workflow. A sandbox test code does not authorize a real customer login or Blackleaf dashboard access.

Read the simulated result separately from the request

Use GET /messaging/messages and GET /messaging/templates on a sandbox host to read sandbox records. Both aliases share those records for the same authenticated workspace. In Blackleaf’s Messages and Message Templates lists, select Sandbox to review the simulated entries.

A queued response is an acknowledgment, not a completed simulation. Successful preparation can produce simulated sent and delivered stages; a failed preparation can produce a failed simulation. An opted-out contact produces a failed simulation.

Account for AI costs, callbacks and contact effects

For sandbox template and SMS/MMS requests, simulateAi defaults to false. This performs simulated review without AI work or an AI charge. Setting it to true requests real AI validation when needed and bills its normal cost. It still does not send a real SMS/MMS or add a delivery fee.

Sandbox templates remain sandbox templates after real AI review. They cannot be used for production sends. Do not describe every sandbox request as free when the caller has opted into real AI validation.

Message processing can make real HTTP callbacks to the configured workspace Message Status URL and, when applicable, the campaign Message Status URL. Use a test receiver or ensure the receiver treats simulated events without triggering real customer actions. Workspace status events include sandbox/simulated markers; campaign callbacks retain their separate payload shape.

Requests save sandbox message/template records. Existing contacts may supply personalization, and optional contact input can update workspace contact data through the normal request flow. Fictional data and a suitable receiver matter even when delivery is simulated.

The Test button in Workspace Settings → Webhooks is a different HTTP-only test. Its payload preview sends no request; its test action sends a marked example to the saved receiver. Neither substitutes for checking the complete API messaging flow.

Review production readiness as a separate step

1. Keep environment configuration explicit. Review the production base URL and credentials separately. A request flag cannot make a production send simulated.
2. Create and review production content. Do not promote a sandbox template ID as a production template.
3. Confirm the actual sender and use case. Simulation does not establish registration approval, provider support, throughput or account readiness.
4. Preserve recipient requirements. Blackleaf requires explicit consent and age confirmation before texting. The intended recipient selects the birthday on file in the message flow; never disclose the saved birthday. Application 2FA verification is a separate check.
5. Review real effects and recovery. Confirm charges, callback processing, contact changes and how uncertain outcomes will be investigated before any separately authorized production test.

The developer guide covers the wider template/send, contact, webhook and production-review flow. The messaging API overview helps scope the integration. Blackleaf Texting can work with supported existing POS systems without a POS switch.

Frequently asked questions

Which Blackleaf API hosts are the messaging sandbox?

Use api-sandbox.blackleaf.io or api-dev.blackleaf.io. They share sandbox messages and templates within the authenticated workspace. Do not treat api-test.blackleaf.io as a documented sandbox alias.

Do I need a real phone to test 2FA verification?

No handset is needed for the sandbox issuance/verification workflow. Use a fictional, valid-format North American phone number and the code returned by the sandbox send response. This does not grant dashboard or real customer access.

Is all sandbox activity free and isolated?

Simulated message delivery has no delivery fee. Real AI validation requested with simulateAi: true can be billed. Records, contact effects and real HTTP callbacks still need review; unrelated endpoints are not covered by a blanket isolation promise.

Does a simulated delivered result prove production will work?

No. It does not establish real carrier delivery, sender readiness, recipient permission, provider approval or production content approval. Review each production dependency separately.

Reference and next steps

Reviewed November 3, 2026 against Blackleaf’s current messaging API reference, API version 2.8.4, and owner-confirmed sandbox guidance. Examples are inert documentation and have not been executed for this article.

Check the public operation schemas before implementing a selected request. Bring the method, base URL, approximate request time, sanitized error and expected result when asking for help. Keep API keys, live codes and private customer data out of support examples.

Explore Blackleaf dispensary texting or discuss your API integration with our team. Start with the workflow you want to rehearse and the production dependencies that still need confirmation.