Sinch Engage API Guide
Sinch Engage, formerly MessageMedia, provides APIs for sending messages, tracking delivery, receiving replies, and managing contacts and messaging resources. This guide links to 21 complete examples using direct HTTPS calls with Chilkat.Http. The examples cover SMS, MMS, text-to-speech, and RCS messaging without requiring a webhook receiver.
Choose a language to update all 21 example links below. Each link opens the complete example in that language. The guide text stays the same.
Use the regional API host assigned to your Engage account: https://au.app.api.sinch.com, https://eu.app.api.sinch.com, or https://us.app.api.sinch.com. Choose the account's region, not the recipient's country. These examples use Engage API keys and endpoints; credentials for a different Sinch product are not interchangeable. See the Sinch Engage API reference for account setup and current request definitions.
The examples require Chilkat 11.6.0 or later and an unlocked Chilkat library. They load an API key and secret from private sinch-engage.json configuration. Set Http.Login to the key, Http.Password to the secret, and Http.BasicAuth to true. Keep these credentials in an application environment you control; do not embed them in a publicly distributed client.
For a request with JSON, build the body with JsonObject.UpdateString, UpdateBool, and UpdateInt, then call Http.HttpJson with the HTTP verb, URL, body, content type, and an HttpResponse object. Use Http.HttpNoBody for a request without a body. Chilkat handles JSON serialization and HTTPS; the examples read the returned fields with JsonObject.
HttpJson and HttpNoBody return false for HTTP 4xx/5xx responses as well as transport errors. A response status of zero means no HTTP response was received. Otherwise inspect HttpResponse.StatusCode before parsing the body. The examples enable JsonObject.Strict so malformed JSON is rejected.Sending messages
Start with Send an SMS. Supply a destination in E.164 format, including its leading plus sign, and the message text. Keep phone numbers and returned IDs as strings. These are live, potentially billable sends: replace the sample number with one you control and have permission to message. Sender registration, channel enablement, and destination rules depend on the account.
A successful submission returns HTTP 202. Save the returned message_id with the local record; acceptance is not delivery. Set delivery_report to true when you need delivery reports. Sending multiple messages uses the same endpoint with a messages array. Split larger jobs into batches of at most 100. Per-message metadata helps correlate records; it is not an idempotency key.
Scheduling adds a future scheduled timestamp. The example calculates it at runtime and sets message_expiry_timestamp to a later UTC time. Expiry limits how long delivery may be attempted. Cancellation uses the saved ID while the message is still scheduled; it cannot recall a sent message, and a last-moment cancellation can race delivery.
MMS adds a subject and hosted media URL that Engage can fetch. A local filename is not an upload. TTS requests spoken-message delivery. RCS must be enabled on the account; the example sends text with a URL action and explicitly supplies a plain-text SMS fallback. Fallback is optional, and recipient capability is resolved asynchronously. Engage's RCS sending and fallback guidance.
Delivery reports and replies
Use a saved message ID to retrieve its current status. Intermediate states describe work in progress, while a delivery result describes the outcome reported to Engage. The lookup API retains messages for 45 days; preserve the history your application needs beyond that period.
Delivery-report and reply polling read pending queues. Each request returns up to 100 records. A record remains available until acknowledged; requesting the next batch is not page-number pagination. The examples fetch one batch, validate its record IDs, save the complete JSON to a private local inbox, and only then acknowledge those IDs. Run them again to drain more records.
For production processing, commit durable storage before acknowledgement and deduplicate using the account plus delivery_report_id or reply_id. Several reports can refer to one message, so message_id is not the report's deduplication key. Use event timestamps when applying updates. If acknowledgement fails, the same records may arrive again. Coordinate account-wide consumers because one poller's acknowledgement affects the others.
The archive preserves fields the application does not yet interpret. This matters for RCS: free-text replies can use a body array instead of content. RCS suggestion taps are sent to a webhook and do not appear in the reply queue. The standalone RCS example uses a URL action and does not depend on processing taps. Account webhooks already configured elsewhere may still receive events.
Contacts and lists
A contact stores profile details and communication channels. Create it once and save the returned contact ID with your local record. The creation example adds an SMS channel with subscriptionState set to SUBSCRIBED; use that state only when you have already obtained and recorded permission to message the person.
Update selected profile fields with PATCH and the saved ID. The update example omits channels and subscription settings so changing a name or note does not alter messaging preferences. Contacts use camelCase JSON fields, whereas many messaging resources use snake_case fields.
Listing contacts follows nextPageToken until no continuation remains. The example checks for repeated tokens and stops at a demonstration limit of 100 pages. A larger application can save the continuation token and resume. The list example creates a list, saves its ID, then adds an existing contact in a second request. If membership fails, resume with that list ID rather than creating another list. List membership neither opts a contact in nor sends a message.
Opt-outs and blocked numbers
Use the blocking API to prevent future messages to a number from the account. The example adds a number to the API's blacklist resource, then checks its authorisation status. A true authorised result means the number is not blocked by that check; it does not prove consent.
The listing example follows the blocking API's pagination token and rebuilds each request against the configured regional host. It does not forward credentials to an arbitrary response-provided URL. Keep blocking controls and contact-channel subscription preferences consistent with the person's choices; they are separate resources. Do not automatically remove a block to make a rejected send succeed.
Numbers, account and reporting
List approved sender addresses to find the sender records available to the account. Check their state and destination eligibility before using them. The sender-address ID is different from the request ID returned during sender registration.
The dedicated-number example searches available inventory by country and service capability. It does not list only numbers you own, purchase a number, or assign one. Both number examples follow continuation tokens rather than assuming the first page is complete.
The credit example reads prepaid balances. Preserve fractional amounts, and do not interpret an omitted balance as zero. Availability depends on the account's billing arrangement.
The message-detail report queries a fixed UTC window for the previous 24 hours and follows pagination.has_next through zero-based pages. It is a historical query, separate from the consumable delivery-report queue. This example uses the v2-preview reporting API. Confirm account access and current schema before production use. Parent accounts can have a wider reporting scope unless an account filter is supplied. For large exports, consider Engage's asynchronous reporting API.
Authentication
Most examples use Basic authentication with the Engage API key and secret over verified HTTPS. The HMAC example provides an alternative for a read-only GET request. It signs the current Date header and exact HTTP request line with HMAC-SHA256, then Base64-encodes the raw digest for the Authorization header. The signing string uses one LF separator and no final newline. Keep the system clock accurate and generate a fresh signature for each request.
The example has no request body. A body-bearing HMAC request additionally requires Content-MD5 and the corresponding signing input, calculated from the exact bytes transmitted. Follow the Engage HMAC authentication specification when adapting it. Signing an API request is different from verifying a signed webhook.
Handle API errors deliberately: review credentials for 401, permissions for 403, and honour Retry-After on 429 before a bounded retry. An interrupted write or 5xx response may leave the outcome uncertain. Reconcile before repeating a send or resource creation. Keep detailed diagnostics private because response bodies and local archives can contain phone numbers and message content.