> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/communication-gateways/secured-messaging-gateways-email-sms-im.md). # Secured Messaging Gateways (Email/SMS/IM) The primary goal of this API is to enable Smartico.ai to send emails and SMS messages without exposing personal and identifiable information (PII), such as end users' phone numbers and email addresses. Smartico can also send messages to the **custom** messengers/notification centers/inboxes, in accordance with the API requirements described below. For native email provider integrations configured through the standard Back-Office wizard, refer to the [Supported Mail gateways](/welcome/technical-guides/communication-gateways/supported-mail-gateways.md) guide. ## Emails via API supplied by customer The customer should provide an API that accepts the following parameters as an HTTP POST JSON Body and is protected by an "**Authorization**" header with a secret value generated by the customer: 1. **ext\_user\_id** / String / platform user id the way it’s reported to Smartico.ai via integration 2. **from\_email\_address** / String / from email address that should be used in the outgoing email 3. **reply\_to\_email\_address** / String / replyTo email address that should be used in the outgoing email 4. **subject** / String / Email subject 5. **body** / String / HTML email body content 6. **text\_body** / String / Text variation on the email 7. **email\_uid** / String / unique email ID on Smartico.ai platform 8. **callback\_url** / String / HTTP API endpoint to be called when email status is changed. Refer to [Reverse integration](#reverse-integration-delivery-statuses) below 9. **activity\_type** / String / Optional parameter indicating the activity requesting the mail sending (only present when sending preview or mail to risk/support). If present the platform should use to\_email\_address to send the mail instead of fetching it from the user profile.\ Possible values: "preview", "Unknown", "EmailCustomerSupport" 10. **to\_email\_address** / String / Optional parameter indicating the email address to send the mail to (only present if there is activity\_type parameter) 11. **custom\_body\_parameters** / Key-Value Map / Optional custom parameters defined in the gateway configuration in the Back-Office. Any key-value pairs configured under Custom Body Parameters are injected directly as root-level properties in the JSON request payload. ``` { "ext_user_id": "hhu234556", "from_email_address": "Amazing ", "reply_to_email_address": "Amazing ", "subject": "The best offer your can find on the market", "body": "..........", "text_body": "Get the offer.....", "email_uid": "ksjhdf3428yqwr8fhjhfkdj", "callback_url": "https://apiXXX.smartico.ai/......callback", "activity_type": "preview", "to_email_address":"test@amazing.co" } ``` **API should return a response as a JSON message, always with a 200 code:** * If mail was accepted * error\_code = 0 * ext\_message\_id - unique email or message ID from the gateway (MUST Have) * If failed * error\_code > 0 * error\_message - explain why the request to send email failed ``` { "error_code": 0, "ext_message_id": "a540f662-45b3-11ee-be56-0242ac120002" } { "error_code": 1, "error_message": "User was not found" } ``` ## SMS/Viber/WhatsApp via API supplied by customer The customer should provide an API that accepts the following parameters as HTTP POST JSON Body and protected by an "**Authorization**" header with a secret value generated by the customer: 1. ext\_user\_id / String / platform user id the way it’s reported to Smartico 2. from\_number / String / Optional, if integration supports 3. body / String / text body content of the message 4. im\_uid / String / unique instant message ID on Smartico platform 5. callback\_url / String / HTTP API endpoint to be called when message status is changed 6. activity\_type / String / Optional parameter indicating the activity requesting the send (present when sending a preview from the Back-Office or operational alerts). If present, the platform should use to\_phone\_number instead of fetching the phone number from the user profile.\ Possible values: "preview", "Unknown" 7. to\_phone\_number / String / Optional parameter indicating the recipient phone number to send to (only present when activity\_type is provided) ``` { "ext_user_id": "hhu234556", "from_number": "Amazing", "body": "Best offer ever", "im_uid": "ksjhdf3428yqwr8fhjhfkdj", "callback_url" : "https://apiXXX.smartico.ai/......callback" } ``` **API should return a response as a JSON message, always with a 200 code:** * If SMS was accepted * error\_code = 0 * ext\_message\_id - unique SMS id from the gateway * If failed * error\_code > 0 * error\_message - describe what is the problem ``` { "error_code": 0, "ext_message_id": "a540f662-45b3-11ee-be56-0242ac120002" } { "error_code": 1, "error_message": "User was not found" } ``` ## Custom IM via the customer-supplied API. Some platforms have their own Notification center, messenger, or pop-up management system. Smartico can be integrated with such solutions and provide customizable templates for resources according to customer requirements. For example, we can use a stock trading platform with its own notification center, which we will call "My custom messenger". You can request from Smartico to define a template for such a message, and following that, you can manage messages based on this template.
In the context of our example, we may require that the template should have the following fields: * body of the message * description * title * action (buy/sell) and instrument symbol (e.g., stock)
As soon as a resource is created, you can build a campaign using the "Custom IM" activity.
### Technical implementation of "Custom IM" API The customer should provide an API that accepts the following parameters as HTTP POST JSON Body and protected by "**Authorization**" header with a secret value generated by the customer: 1. **ext\_user\_id** / String - platform user id, the way it’s reported to Smartico 2. **body** / String - text body content of the message 3. **im\_uid** / String - unique instant message ID on Smartico platform 4. **callback\_url** / String - HTTP API endpoint to be called when message status is changed 5. **extension** (optional) / Object - consists of field, name, and value that are defined in the custom instant message template (e.g., description, title, action, instrument from our example). 6. **campaign\_id** / String - The unique id of the Smartico campaign that triggered this message\ \ Note: Smartico configures the names and types of the **extension** fields based on customer requirements. ``` { "ext_user_id": "hhu234556", "from_number": null, "body": "Best offer ever", "im_uid": "ksjhdf3428yqwr8fhjhfkdj", "callback_url" : "https://apiXXX.smartico.ai/......callback", "extension": { "title": "Microsoft is raising", "description": "The bullish trend...", "action": "BUY/SELL", "instrument": "MSFT" }, "campaign_id": "3716729" } ``` **API should return a response as a JSON message, always with a 200 code:** * If the custom instant message was accepted * error\_code = 0 * ext\_message\_id - unique ID of the message from the gateway * If failed * error\_code > 0 * error\_message - describes the problem ``` { "error_code": 0, "ext_message_id": "a540f662-45b3-11ee-be56-0242ac120002" } { "error_code": 1, "error_message": "User was not found" } ``` ### Process of setting up Custom IM 1. **Define the Required Fields**\ Determine the fields that your **Custom IM resource manager** should include. In the example provided, the fields were `"title"`, `"description"`, `"action"`, and `"instrument"`, but you are free to define any fields relevant to your use case. Fields can be: * Simple text fields (e.g., strings) * Predefined options (limited choices) * Boolean flags (e.g., yes/no) * Media assets (e.g., images) 2. **Request Smartico to Enable Your Fields**\ Once you have finalized the list of fields, create a **JIRA ticket** requesting Smartico to enable them in the system. 3. **Implement API for Receiving Custom IM Requests**\ Develop an API on your side that can **accept requests** when a Custom IM needs to be sent to a specific user. 4. **Implement Reverse Integration for Status Updates**\ Follow the instructions in the next section to **report status updates** back to Smartico for each instance of sending a Custom IM. 5. **Register Your API in Smartico BackOffice** * Navigate to **"Label \ Gateways \ Instant messages."** * Create a new **Custom IM gateway** * Provide the URL of your **API endpoint** * Define the '**Authorization**' key value for additional protection of the HTTP call. * Optionally define HTTP headers that your API may expect 6. **Create and Deploy a Custom IM Campaign** * Go to **"Marketing \ Assets \ Instant messages."** * Create a new resource with the type **"Custom IM."** * Build a marketing campaign that will send this resource to users ## Reverse Integration / Delivery Statuses Upon the customer receiving any status update regarding email/sms/custom IM deliverability, it should call the Smartico.ai API via a simple HTTP GET to the endpoint provided in the original request. This is needed for two main reasons. **To analyse the performance of communication channels**
**To build campaign flows based on the activity in the communication channel**
To report a change of the status, you need to use the **callback\_url** that Smartico provides in each request to send communication, and append it with two parameters: * **ext\_message\_id** - ID of the message, same as in your response to the initial request for sending communication * **status** - one of the following string values * accepted * delivered * failed * rejected * complained * opened * unsubscribed * clicked {% hint style="warning" %} The callback must supply the exact **ext\_message\_id** returned in your gateway's response to the original send request. Smartico matches status updates strictly against recorded message records. If the ID is modified, truncated, or substituted, Smartico cannot match the message and silently drops the callback, meaning delivery, open, click, and unsubscribe events will not be recorded. {% endhint %} The final URL to send status will look like this: **71e92bca-48a8-11ee-be56-0242ac120002**\&status=**delivered** Parameters in red must be appended. {% hint style="info" %} If you cannot store the callback URL on your side, you can use a fixed URL; in such case, you need to know * Domain and callback path, which depend on which environment your label is hosted (e.g. `api3.smartico.ai` for environment 3). You can obtain the exact fixed callback path for your environment from the Smartico integration team, or use the dynamic callback URL provided in each send payload. * api\_key corresponds to what is called "Label private API key.", You can request it in the technical chat with the Smartico team, or you can find it in the Smartico BackOffice in "Tools \ REST API." * type - depends on the kind of message, could be "email", "sms" or "cim" (for Viber, WhatsApp and Custom IM) {% endhint %} **Response as JSON message, always with 200 code:** * In case of success, the response returns HTTP status code 200 with a JSON body containing `{"message": "", "error_code": 0}`. * In case of an error, the response returns HTTP status code 500 with a JSON body containing `{"message": "", "error_code": 0}`. ``` {     "duration": 1,     "errCode": 9999,     "errMsg": "Error message text",     "cid": 99999 } ``` ## Frequently Asked Questions ### How can I test my secured gateway integration before launching live campaigns? In the Back-Office, navigate to your message template under **Marketing \ Assets \ Mail** (or **Instant messages**) and click **Send Preview**. For secured gateways, Smartico dispatches a test request containing `activity_type: "preview"` alongside the recipient's test email address or phone number. Your gateway implementation must check for the presence of `activity_type` and route the test message directly to the provided recipient address or phone number, rather than attempting to resolve a platform user by `ext_user_id`. ### Why is configuring the callback URL required for Impression exit points and campaign branch conditions? Campaign journeys that branch on **Delivered** or **Impression / Opened** rely on delivery status notifications sent back from your gateway. When a message is dispatched, Smartico logs the communication as sent and awaits a callback. If your system does not report `delivered` or `opened` events to the Smartico callback URL, the journey flow cannot detect that the recipient received or opened the message (unless the recipient clicks a tracked link), leaving players waiting at the branch condition until timeout. ### If I set up a new gateway or remove an existing one, will existing campaigns automatically use the new gateway? Campaigns configured with **Automatic gateway selection** dynamically route through whichever active gateway matches the campaign's channel, brand, and filtering conditions. However, if an existing campaign activity was explicitly assigned to a specific named gateway, it will remain bound to that gateway. When replacing or retiring a gateway, inspect your active campaign activities in the Journey builder to ensure they are updated to the new provider. ### Can Smartico send messages to players who have no email address or phone number in Smartico? Yes, if your gateway holds the contact data and the **Send to players without email or phone in Smartico** setting in **Label settings** is on; ask your Success manager to change it. When it is on, an email or IVR call to a player with no email address or phone number in Smartico is not failed for that reason: Smartico sends it with a placeholder address, and your gateway must find the real address itself (for example, by `ext_user_id`). SMS and other instant messages are also no longer failed because the phone number is missing or invalid. Side effect: in the Back-Office, the buttons that send a personal message to a player are no longer disabled, even for players who opted out. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.smartico.ai/welcome/technical-guides/communication-gateways/secured-messaging-gateways-email-sms-im.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.