Automations

This guide covers building automated messaging flows with the API. This is separate from the EZ Texting Workflows product, which provides a visual builder for automations without code.

With the API, you combine building blocks: inbound messages (any text someone sends to your number), keywords (specific words that trigger opt-ins or actions), webhooks (event listeners), contacts and groups (audience management), and messages with sendAt (scheduled delivery). Inbound messages are the most common trigger — a customer texts you, your webhook fires, and your app responds. Keywords are a specific case of that where a particular word drives the logic.

Keywords

Keywords are words that contacts text to your number to trigger an action — typically opting into a contact group. They're the entry point for most automation flows. Keywords use the keyword string in the path (not an ID).

cURL

Copy

# Check if a keyword is available
curl --request GET \
  --url "https://a.eztexting.com/v1/keywords/JOIN/check" \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)"

# Acquire the keyword (requires credit card on file)
curl --request POST \
  --url https://a.eztexting.com/v1/keywords/JOIN/acquire \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
  --header "Content-Type: application/json" \
  --data '{"creditCardLastFour": "4242"}'

# Configure the keyword — set auto-reply and group assignment
curl --request PUT \
  --url https://a.eztexting.com/v1/keywords/JOIN \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
  --header "Content-Type: application/json" \
  --data '{
    "autoReply": "Welcome! You are now subscribed to Acme Co updates. Reply STOP to unsubscribe.",
    "contactGroupId": "987654"
  }'

Keyword lifecycle

1. Check availability — GET /v1/keywords/{keyword}/check
2. Acquire — POST /v1/keywords/{keyword}/acquire (requires creditCardLastFour)
3. Configure — PUT /v1/keywords/{keyword} to set auto-reply and group assignment
4. Monitor — GET /v1/keywords to list, GET /v1/keywords/{keyword} for details
5. Release — DELETE /v1/keywords/{keyword}/release when no longer needed

Webhooks

Webhooks push real-time notifications to your server when events occur. Instead of polling the API, your server receives an HTTP POST request the moment something happens. Create subscriptions with callbackUrl (required), type (required), and optionally a secret for signature verification.

cURL

Copy

# Create a webhook subscription for inbound messages
curl --request POST \
  --url https://a.eztexting.com/v1/webhooks/subscriptions \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
  --header "Content-Type: application/json" \
  --data '{
    "callbackUrl": "https://your-server.com/webhooks/eztexting",
    "type": "inbound_text.received",
    "secret": "your_webhook_secret"
  }'

# Create a webhook for keyword opt-ins
curl --request POST \
  --url https://a.eztexting.com/v1/webhooks/subscriptions \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
  --header "Content-Type: application/json" \
  --data '{
    "callbackUrl": "https://your-server.com/webhooks/opt-in",
    "type": "keyword.opt_in",
    "secret": "your_webhook_secret"
  }'

# List your active webhook subscriptions
curl --request GET \
  --url https://a.eztexting.com/v1/webhooks/subscriptions \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)"

Webhook event types

Workflow patterns

Pattern 1: Keyword opt-in flow

Contact texts a keyword, gets added to a group, and receives a welcome message.

1. Acquire and configure a keyword (one-time setup)
2. Create a contact group for subscribers
3. Subscribe to the keyword.opt_in webhook event
4. When the webhook fires, your app creates/updates the contact, adds them to the group, and sends a welcome message
5. Schedule follow-up messages using sendAt

Pattern 2: Welcome drip sequence

After opt-in, send a series of messages over time. Your app calculates the sendAt timestamps and creates each scheduled message.

cURL

Copy

# Immediate welcome message
curl --request POST \
  --url https://a.eztexting.com/v1/messages \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
  --header "Content-Type: application/json" \
  --data '{
    "toNumbers": ["15551234567"],
    "message": "Welcome to Acme Co! Thanks for subscribing. Here is what to expect: weekly tips and exclusive offers.",
    "messageType": "SMS",
    "companyName": "Acme Co"
  }'

# Day 1: Tips message (scheduled)
curl --request POST \
  --url https://a.eztexting.com/v1/messages \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
  --header "Content-Type: application/json" \
  --data '{
    "toNumbers": ["15551234567"],
    "message": "Tip #1: Did you know you can customize your notification preferences? Visit https://example.com/prefs",
    "messageType": "SMS",
    "companyName": "Acme Co",
    "sendAt": "2026-04-16T12:00:00Z"
  }'

# Day 3: Offer message (scheduled)
curl --request POST \
  --url https://a.eztexting.com/v1/messages \
  --header "Authorization: Basic $(echo -n 'your_username:your_password' | base64)" \
  --header "Content-Type: application/json" \
  --data '{
    "toNumbers": ["15551234567"],
    "message": "As a new subscriber, enjoy 15% off your first order with code WELCOME15. Shop now: https://example.com/shop",
    "messageType": "SMS",
    "companyName": "Acme Co",
    "sendAt": "2026-04-18T12:00:00Z"
  }'

Pattern 3: Inbound message auto-responder

1. Subscribe to inbound_text.received webhook
2. Your server receives the message content and sender phone number
3. Apply your business logic (check message content, look up contact, consult rules)
4. Send a reply via POST /v1/messages — automatically threaded into the conversation
5. Update the contact's custom fields or group membership based on the interaction

Pattern 4: Appointment reminders

1. Appointment booked in your system (not an EZ Texting event)
2. Create or update the contact via POST /v1/contacts
3. Schedule reminders: 24 hours before, 1 hour before
4. Store message IDs so you can cancel with DELETE /v1/messages if the appointment changes

Blocking numbers

Use POST /v1/blocks to prevent outbound messages to specific phone numbers. Pass a phoneNumbers array. This is for manual exclusions beyond standard STOP opt-out handling (which EZ Texting processes automatically).

Endpoints reference

Best practices

• Use webhooks, not polling. Webhooks deliver events in real time with zero wasted requests.
• Make webhook handlers idempotent. Your handler may receive the same event twice due to retries. Check before creating duplicates.
• Respond to webhooks quickly. Return 200 immediately and process work asynchronously in a background queue.
• Verify webhook signatures. Use the secret you set when creating the subscription to verify incoming requests are genuine.
• Store message IDs for scheduled sends. You'll need them to cancel remaining messages if a contact opts out.
• Respect quiet hours. Don't schedule messages before 8 AM or after 9 PM in the recipient's time zone.

Next steps

• Transactional Messaging — The message sending endpoints used in automation flows
• Conversational Messaging — Manage two-way threads triggered by inbound messages
• Marketing Campaigns — Send campaigns to the groups your automations build
• Contact Management — Create and organize contacts in your workflows
• Webhooks — Full webhook setup and event documentation
• API Reference — Full interactive endpoint documentation