Messaging Concepts

Messaging is one of eCourtDate's core capabilities. This page covers how messages are created, delivered, scheduled, and tracked.

What Is a Message?

A message is a single communication sent or received through eCourtDate. Messages support multiple channels:

Field	Description
uuid	Unique identifier assigned by eCourtDate.
direction	outbound (sent by the agency) or inbound (received from a contact).
channel	Delivery channel: text, email, voice, or push.
status	Current delivery status (e.g., queued, sent, delivered, failed).
subject	For email, this is the subject line. For SMS and voice, the subject is concatenated with the content (separated by a space) to form the full message body. Default max length is 255 characters.
content	The message body. Default max length is 2,000 characters for new agencies.
send_now	When true, the message is sent immediately rather than queued for scheduled delivery.
skip_duplicate	When true, duplicate checking is disabled — the message will be sent even if a duplicate already exists for the same contact and event. When false or not set, eCourtDate performs a duplicate check and prevents duplicate messages.

How Messages Are Created

Messages can be created in several ways:

• Flows: Ideal for sending a sequence of messages based on a date/time field — such as an event date, payment due date, or task due date. Records are linked to a flow, and the flow generates messages relative to that date. For example, a flow can send a reminder 7 days before a hearing, another 3 days before, and a final reminder the day of. Flow-generated messages are created ahead of time and are available in the Admin Application and API for review before they are sent.
• Auto Messages: Ideal for one-off or recurring notifications triggered by a condition rather than a date sequence. Each auto message is configured with a trigger — for example, "when an event status is set to Continued" or "when a payment status is Overdue." When a record meets the trigger condition, the auto message fires. Multiple auto messages can apply to the same record if multiple conditions are met.
• Manual: Users can create individual one-off messages directly in the Admin Application or via the API.
• Bulk Actions: Users can send mass messages to a filtered set of recipients through the Admin Application. Bulk actions can be run immediately, scheduled for a future date, or set to recur on a defined schedule.
• API: Messages can be created programmatically via POST /v1/messages. Set send_now: true for immediate delivery or omit it to schedule for later.

Merge Tags

Merge tags are placeholders written in square brackets (e.g., [ClientFirstName], [EventDate]) that get replaced with actual data when a message is sent. They work in message templates, flows, and auto messages. If a merge tag references a field that is empty, it is omitted from the final message.

Merge tags also support conditional labels using % syntax — for example, [%Case Number: %CaseNumber] will only show the label and value if the case number exists.

For the complete list of all available merge tags and usage details, see Merge Tags.

Message Syncing

When a record (event, payment, case, etc.) is linked to a flow, eCourtDate automatically generates and schedules messages based on the flow's rules. This is the initial sync — the flow evaluates the record's data (dates, contact information, status) and creates the appropriate messages ahead of time.

How syncing works

1. A record is created or imported with a flow assigned to it.
2. eCourtDate evaluates the flow's rules against the record's data.
3. Messages are generated and scheduled according to the flow's configuration (e.g., "7 days before event date", "3 days before event date", "day of event").
4. The generated messages are available in the Admin Application and API for review before they are sent.

Resyncing

When a record is updated in any way — the date changes, the location is corrected, a contact is added or removed, the status is modified, or any other field is changed — eCourtDate automatically resyncs the associated flow-generated messages. The resync process re-evaluates the flow's rules against the updated data and regenerates the scheduled messages accordingly.

The scope of a resync depends on which record type is updated:

• Client updated: Resyncs all records related to that client. For example, if a client's preferred language is changed from English to Spanish, all existing flow-generated messages across that client's events, payments, and other linked records are resynced. If the flow includes a Spanish-language template, the regenerated messages will be in Spanish.
• Event updated: Only that specific event's messages are resynced. For example, if a hearing is rescheduled from March 15 to March 22, the reminder messages for that event are regenerated with the updated date and timing.
• Contact updated: Resyncs messages for records linked to the affected client, since delivery targets may have changed. For example, if a contact is removed, messages to that contact are removed.

No need to manually delete and recreate messages after a data update.

What does not resync

Auto messages do not resync. They fire once when the trigger condition is met. If a record changes after an auto message has already been sent, the auto message does not re-evaluate or regenerate.

Inbound vs. Outbound

• Outbound (direction: outbound): Messages sent by the agency to a contact (reminders, notifications, alerts).
• Inbound (direction: inbound): Messages received from a contact (replies, responses). Inbound messages are captured and stored so agencies can see responses in the Admin Application and via the API.

Message Statuses

Status	Channels	Description
dispatched	All	Message has been created and dispatched for sending.
queued	All	Message is queued and waiting to be sent.
sent	All	Message has been handed off to the delivery provider.
delivered	All	Delivery confirmed by the provider.
received	All	Used for inbound messages received from a contact.
failed	All	Delivery failed (e.g., invalid number, provider error).
bounced	Email	Message bounced back (e.g., invalid email address, full mailbox).
answered	Voice	The contact answered the voice call.
opened	All	The recipient clicked a trackable eCourtDate link in the message. For email, this can also mean the recipient opened the email. When a link is clicked, the opened_at field is populated. A message can move to opened after delivered.

Scheduled Messages

Messages can be scheduled for any date and time in the future. When a message is scheduled, it remains in a pending state until the scheduled time arrives, at which point eCourtDate dispatches it for delivery. Scheduled messages can be reviewed, edited, or canceled before they are sent.

Flow-generated messages are scheduled automatically based on the flow's rules (e.g., "3 days before the event date"). Messages created manually, via bulk actions, or through the API can also be assigned a future send date.

Send Mode

eCourtDate can run messages in live mode (actually delivered) or simulate mode (not delivered). Simulate mode lets you test messaging workflows without sending anything to real recipients. There are three places where simulate mode can be set.

Agency send mode

Every agency has a send mode setting: live or simulate. This is the broadest control. When the agency is set to simulate, all outbound messages for that agency are simulated.

An important detail: the agency send mode is checked when a message is sent, not when it is created. So if you create messages while the agency is in simulate mode, then switch the agency to live before those messages are scheduled to go out, they will be sent live.

Per-message simulate

You can mark an individual message as simulated by setting the test attribute via the API. That message will always be simulated, even if the agency is in live mode. This is useful when you want to test a single message without changing the agency setting.

Flow and auto message simulate

Flows and auto messages each have their own simulate setting. When enabled, messages generated by that flow or auto message are marked as simulated at the time they are created.

Changing the setting later does not retroactively change messages that were already created. For example, if a flow has simulate enabled and generates 50 messages, then you turn simulate off on that flow, those 50 messages remain simulated. New messages generated after the change will follow the agency send mode as usual.

Simulated Messages

Simulated messages go through the full creation and scheduling process but are never actually delivered. Instead, they receive randomly assigned statuses — delivered, failed, bounced, etc. — to mimic what real delivery looks like.

warning

These statuses are random and do not reflect real delivery results. If you see "failed" or "bounced" on simulated messages, nothing is wrong. This is expected behavior. Make sure your agency is in live mode before expecting real delivery.

Carrier Registration

Before sending SMS messages in the United States, your agency must complete carrier registration. This involves registering your agency as a brand and then registering one or more messaging campaigns with US mobile carriers. Unregistered traffic is blocked.

For full details on the registration process, number types (10DLC, toll-free, and short code), campaign setup, throughput, and best practices, see Carrier Registration.

Channel Limitations and Common Issues

Each delivery channel has its own limitations and typical issues that can affect message delivery.

Text (SMS)

Limitations:

• Messages are limited to 160 characters per segment (GSM-7) or 70 characters (UCS-2). Longer messages are split into multiple segments, up to a maximum of 10 segments. See SMS Encoding and Message Length for details.
• More segments per message increases delivery cost.

Common issues:

• Carrier filtering: Carriers (T-Mobile, AT&T, Verizon, etc.) use automated filters to block messages that look like spam. Messages can be silently filtered without any error returned — the delivery report may say "delivered" even though the recipient never received it. Including opt-out language (e.g., "Reply STOP to opt out") reduces the chance of filtering.
• 10DLC registration: All application-to-person (A2P) SMS sent over long code numbers in the US must be registered through The Campaign Registry (TCR). Unregistered traffic is blocked by carriers. eCourtDate handles 10DLC registration, but agencies should confirm their campaigns are registered and approved.
• Throughput limits: Carriers assign sending limits per brand based on a trust score. Exceeding these limits results in messages being queued or rejected. Long codes are generally limited to low throughput (as few as 10 messages per minute per number). Toll-free and short code numbers support higher throughput. See Message Sending Limits for platform-level sending rates and how to request increases.
• Opt-out compliance: When a recipient replies STOP, their number is added to an opt-out list. Sending to opted-out numbers results in failed delivery and can damage your sender reputation with carriers.
• Invalid or landline numbers: SMS cannot be delivered to landline numbers. Messages sent to invalid, disconnected, or landline numbers will fail.
• Quiet hours: Some carriers delay or block messages sent outside of normal hours. Be mindful of recipient time zones when scheduling messages.

Email

Limitations:

• Default maximum message size is 10 MB (including HTML, headers, and attachments). Can be increased to 40 MB.
• A subject line is required.
• Excessively large emails may be clipped by the recipient's email client (Gmail clips emails over approximately 102 KB of HTML).

Common issues:

• Spam filtering: Recipient email providers (Gmail, Outlook, Yahoo, etc.) use content filters to flag or redirect messages to spam. Emails with excessive links, large images, missing unsubscribe headers, or spammy language are more likely to be filtered.
• Bounces: A hard bounce means the email address is invalid or does not exist — the message will never be delivered. A soft bounce is a temporary issue (full inbox, server error) and may succeed on retry. High bounce rates damage your sending reputation and can lead to sending restrictions.
• Complaints: When recipients mark an email as spam, it generates a complaint. Maintaining a complaint rate below 0.1% is critical. Rates above 0.5% can result in sending being paused.
• Authentication failures: Emails are more likely to land in spam if the sending domain is not properly configured with SPF, DKIM, and DMARC records. These are configured at the domain level during agency setup.
• Rendering differences: HTML email templates render differently across email clients. What looks correct in Gmail may break in Outlook. Keep email templates simple and test across clients.
• Image blocking: Many email clients block images by default until the recipient explicitly loads them. Do not rely on images alone to convey important information.

Voice

Limitations:

• Message content is converted to speech using text-to-speech (TTS). Keep messages concise — long messages are difficult for recipients to follow and increase call duration.
• TTS pronunciation may not always be accurate for names, addresses, or abbreviations. Spelling out difficult words or using phonetic hints can help.

Common issues:

• Unanswered calls: If the recipient does not answer, the message is not delivered. Voicemail delivery depends on the recipient's carrier and voicemail configuration.
• Spam likely labeling: Carriers and apps (Hiya, Nomorobo, carrier analytics) may label outbound calls as "Spam Likely" or "Telemarketer" if the calling number has low reputation, missing CNAM registration, or high call volume with short durations. Proper caller ID registration reduces this risk.
• Call screening: Recipients may have call screening enabled that blocks or screens unknown numbers. This is increasingly common on both iOS and Android.
• Number formatting: Voice calls require properly formatted numbers including the country code. Incorrectly formatted numbers will fail.

Push

Limitations:

• Content length limits vary by device and operating system. iOS and Android handle push notifications differently, and messages are typically truncated beyond a few hundred characters.
• Push notifications require the recipient to have the app installed and notifications enabled.

Common issues:

• Permission denied: If the recipient has not granted notification permissions or has later disabled them, push notifications are silently dropped.
• Do Not Disturb and Focus modes: iOS Focus modes and Android Do Not Disturb can delay or suppress push notifications. Messages may be batched and delivered later rather than in real time.
• Battery optimization: Android devices (especially Samsung, Xiaomi, Oppo, and Huawei) aggressively manage background activity. Push notifications may be delayed or blocked until the user unlocks their device.
• Expired tokens: If the app is uninstalled or the device token expires, push delivery fails silently.
• Truncation: The visible length of a push notification varies by device screen size and whether images or action buttons are included. There is no universal character limit — test on multiple devices.

SMS Encoding and Message Length

SMS messages use one of two encoding types, and the encoding directly affects how many characters fit in a single segment. The default encoding depends on the phone number type used to send the message:

Sender Type	Default Encoding	Fallback
Long code	GSM-7	UCS-2 (UTF-16)
Toll-free	GSM-7	UCS-2 (UTF-16)
Short code	ASCII 7-bit	UCS-2 (UTF-16)
Alphanumeric	GSM-7	UCS-2 (UTF-16)

If the message contains characters not supported by the default encoding, the system automatically falls back to UCS-2.

Characters Per Segment

Each SMS segment holds 140 bytes. The number of characters that fit depends on the encoding:

Encoding	Single Segment	Multipart (per segment)
GSM-7	160 characters	153 characters
ASCII 7-bit	160 characters	153 characters
UCS-2 (UTF-16)	70 characters	67 characters

Multipart messages reserve a few bytes per segment for reassembly headers, which reduces the usable character count. The maximum is 10 segments per message. Messages that exceed 10 segments will not be sent.

Common Pitfalls

• Curly quotes and special punctuation (e.g., " " ' ' —) are not part of the GSM-7 character set. A single curly quote in an otherwise GSM-7 message forces the entire message to UCS-2 encoding, cutting the per-segment limit from 160 to 70 characters.
• Emojis always require UCS-2 encoding. Each emoji consumes 4 bytes and counts as 2 characters, further reducing segment capacity.
• Extended GSM-7 characters (~, ^, |, \, {, }, [, ]) require an escape code and count as 2 characters each.
• Copied text from Word or Google Docs often contains hidden curly quotes or special characters that trigger UCS-2 encoding. When writing message templates, use plain text or verify encoding before saving.

More segments per message may increase delivery cost. Keep SMS content concise and avoid unnecessary special characters to minimize segment count.

Template and Message Limits FAQ

Is there a character limit for message templates? Yes. Messages are constructed from two fields: subject (default max 255 characters) and content (default max 2,000 characters). How these fields are used depends on the channel:

• Email: subject is the email subject line. content is the email body.
• SMS and Voice: subject and content are concatenated together with a space to form the full message body.
• Push: content is the notification body.

Within those limits, per-channel constraints still apply:

• SMS: The maximum is 10 segments (1,530 characters for GSM-7 or 670 characters for UCS-2). The combined subject + content length counts toward this limit. Even if the content limit is raised, SMS messages cannot exceed 10 segments.
• Email: The default maximum message size is 10 MB (including HTML markup, headers, and attachments). This can be increased up to 40 MB per message.
• Voice and Push: No strict per-channel limit beyond the field limits, but keep content concise for clarity and device compatibility.

Does the character count include raw HTML markup? Yes. For email templates, the character count includes all raw HTML markup (<p>, <br>, <table>, <div>, etc.), not just the visible text. A template that appears short to the reader may be significantly larger when HTML tags, inline styles, and formatting are included. Keep this in mind when designing email templates.

What is the maximum supported character length? By default, subject is 255 characters and content is 2,000 characters. Per-channel maximums:

• SMS: 1,530 characters (GSM-7) or 670 characters (UCS-2) for the combined subject + content, based on the 10-segment maximum.
• Email: 10 MB by default (approximately 10 million characters of plain text, less with HTML and attachments). Can be increased to 40 MB.

Is it possible to increase the limit?

• Content field limit: Yes. Submit a ticket through the Help Center requesting the increase for each agency that needs it. Limits are set per agency, so a separate request is required for each one. Note that increasing this limit does not change the SMS segment maximum — SMS messages are still capped at 10 segments regardless of the content field limit.
• SMS: No. The 10-segment maximum is a carrier-level limitation and cannot be changed.
• Email: Yes. Submit a support request through the Help Center to increase the email message size limit for your agency.