This API is a service provided by E-goi to send transactional messages.

Transactional Messaging is a 1-to-1 communication channel, usually from an organization directed to a specific consumer.
They can be triggered by:

• Actions - The consumer interacts with the organization (ie.: online shopping);
• Time - The consumer's actions are time-bounded by the organization (ie.: period of inactivity).

Because of the nature of these messages,
it is expected that the consumer is interested in the content of these messages.
Therefore, they have a different treatment from marketing messages, and have a higher acceptance and opening rate.

DISCLAIMER

Please notice that this platform is more delicate in regards to the nature and processing of its messages.

It should NOT be used as a mean of mass marketing, scams, phishing or overall unruly behaviour.

Failure to comply may lead to limitation of use and even termination of account.

Transport Layer Security (TLS) is a widely used authentication and encryption protocol that establishes a secure communications channel for data-in-transit while ensuring that the client and server can validate one another.
Our API requires TLS 1.2 or TLS 1.3. We recommend TLS 1.3.

TLS 1.3 ciphers

• TLS_AES_256_GCM_SHA384 (0x1302) ECDH x25519 (eq. 3072 bits RSA) FS
• TLS_CHACHA20_POLY1305_SHA256 (0x1303) ECDH x25519 (eq. 3072 bits RSA) FS
• TLS_AES_128_GCM_SHA256 (0x1301) ECDH x25519 (eq. 3072 bits RSA) FS

TLS 1.2 ciphers

• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030) ECDH x25519 (eq. 3072 bits RSA) FS
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f) ECDH x25519 (eq. 3072 bits RSA) FS
• TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 (0x9f) DH 4096 bits FS
• TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 (0x9e) DH 4096 bits FS

Character limits apply to your SMS, depending on how your message is encoded.

If you use unicode, you can include special characters and emojis (your SMS will be limited to 70 chars overall).

If you don’t need special chars, opt for gsm0338 encoding to increase your character limit to 160 chars per message.

If the message exceeds the character limit, you can use the maxCount field in your payload to set how many parts it will be split into. More info

Get started quickly with Transactional with our integration tools. Our SDK is a modern open source library that makes it easy to integrate your application with Transactional services.

• PHP
• JAVA
• C#
• GO

The Transactional SMTP Service consists of a simple SMTP server, listening to SSL/TLS connections on port 1587.

To configure your preferred client you need to add an account with the same e-mail as the desired client's user -
it will be used to identify the real sender in the client list of senders.
For the example below we will use the sender - info@example.com - and the username of client's user account - egoi@example.com.

The configuration for the Outgoing SMTP Server in Thunderbird would be as follows:

After you add this configuration, you can use it by sending from the info@example.com account and using the configured SMTP Server.
After you hit send the first time, the program should challange you for a password to authenticate -
use the password you normally you to access the E-Goi Backoffice with the configured User Name (egoi@example.com in this case).

// This example uses PHPMailer 
require 'PHPMailerAutoload.php'; 
 
// Configure PHPMailer instance 
$mail = new PHPMailer; 
$mail->isSMTP(); 
$mail->SMTPAuth = true; 
$mail->Host = "bo51.e-goi.com"; 
$mail->Port = 1587; 
$mail->SMTPSecure = "tls"; 
 
// Username and Password 
$mail->Username = "egoi@example.com"; 
$mail->Password = "the password"; 
 
// From 
$mail->setFrom('info@example.com', 'Sales Dept.'); 
    // .. or $mail->addCustomHeader('X-Sender-Hash: abcdef1234567890abcdef1234567890'); 
 
// Destination 
$mail->addAddress('johndoe@mail.com', 'John Doe'); 
    // .. or $mail->addCustomHeader('X-Reply-To-Hash: abcdef1234567890abcdef1234567890'); 
 
// Set the appropriate encoding for subject/body/alternate 
$mail->CharSet = "UTF-8"; 
 
$mail->Subject = 'Here is your reciept'; 
 
// The content is read from a file on the filesystem 
$mail->msgHTML(file_get_contents("/path/to/receipt.html")); 
 
// [optional] Set the text version of the message 
$mail->AltBody = file_get_contents("/path/to/receipt.txt"); 
 
// Define custom headers 
$mail->addCustomHeader("X-Open-Tracking-Enabled: true"); 
$mail->addCustomHeader("X-Click-Tracking-Enabled: true"); 
 
// Define Registered headers  
$mail->addCustomHeader("X-Registered: true"); 
 
// Define message priority (optional)  
//(X-Priority header is overriden by PHPMailer when using addCustomHeader) 
$mail->Priority = "urgent"; 
 
//send the message, check for errors 
if (!$mail->send()) { 
    echo "Mailer Error: " . $mail->ErrorInfo; 
} else { 
    echo "Message sent!"; 
} 

Alert are a routine of messages, prepared in advance, to be triggered by events set by the user. The channel of the message can be either Sms or Email.

The Acknowledge Alerts entails two distinct steps: Create and Execute.

Create is the step where a Acknowledge Alerts flow (or template) is set.
It requires some identifying information, as well as the message to be sent.

Execute takes the Acknowledge Alerts flow, customizes the messages with To addresses and merge tags. Then, it starts the flow by sending the first message.

When the Alarm is executed, the message is resent after the interval,
unless someone responds to it (Acknowledge) or the repetition limit is reached.

The alert can be in specific states. the following is a list of states an alert can be in.

Multi-channel are a set of pre configured messages, using all available channels,
whose sending depends on the state of the previous message.

The Multi-channel entails two distinct steps: Create and Execute

Create is the step where a multichannel flow (or template) is set.
It requires some identifying information, as well as the messages sorted and conditions defined.

Execute takes the multichannel flow, customizes the messages with To addresses and merge tags. Then, it starts the flow by sending the first message.

In order to track the state of the messages the following parameters will be set to true.

• openTracking

• clickTracking

The following diagram shows the workflow of the multi-channel.

The following diagram shows the states of the multi-channel.

Condition of messages

Verify is the E-goi version of a 2-Factor Authentication (2FA) via Sms messaging.

A 2FA request is sent when a sender (organization) needs to verify the identity of a recipient.
To do this an intermediary (E-goi) will provide an independent tunnel between the two.
A successful string of events should be the following:

1. The sender requests a validation code to be sent to the recipient;
2. The system generates the code;
3. The system sends the code to the recipient;
4. The recipient submits the code to the sender;
5. The sender submits the code in the system;
6. The system validates the code.

In this series of events some alternatives may occur.

• Alternative - The sender wants to cancel the Verify request.
  • Solution - The sender can cancel the Verify request at any point in time before the recipient validates the code.
• Alternative - The code validity expires.
  • Solution - The system marks the request as expired.
• Alternative - The recipient submits the wrong code.
  • Solution - The system waits for the correct code (while request has not expired).

Emails can be send using the API, or using the SMTP Server.
The API should be the preferred method, as it is better documented, and have much more functionalities. However, for simple emails, SMTP use is fine. See below for its configuration.

Emails are composed using different sets of information:

The Sender can not interact with the status and events.
He can only follow and check the state of the message.

The following is a diagram of all the states an email can be in.

Emails can have file attachments, whether inline with the email text, or as an attachment. The maximum size for an attachment is 5Mb.

Attachments are a special feature, available to those who request it. If you wish to send attachments,
please contact support using the help menu on your E-Goi Backoffice.

inline attachments should be
Emails can have file attachments, whether inline with the email text, or as an attachment. The maximum size for an attachment is 5Mb. Attachments are a special feature, available to those who request it. If you wish to send attachments, please contact support using the help menu on your E-Goi Backoffice

If you want to send an image as an inline attachment, you should include the attachment as followed by the documentation, with the disposition \inline. Then, simply add the following tag to your message:

<img src=\cid:{{index}}\/>

Please beware of escaping the quotation marks in the payload. The index is the position of the image in the array of attachments, so if the attachment to include is in position 0, then the tag should be:

<img src=\cid:0\/>

Files can be sent using the Mime Type x- namespace. However, they are considered experimental, and mostly are used to support older software.

Please note that some email inboxes block certain file extensions, mostly related to code files ( .vb, .js, .py), shell commands (.bat, .ps1, .ksh, .msh) or executable files (.exe, .jar, .apk). We do not advise any attempts to send files of these nature.

Slingshot allows its users to send emails and Sms through its API, and to keep detailed logs from all steps of a message's lifecycle.
This feature is called Registered Message.

Our records detail dates and times, sender and recipient information, subject and content of the message and its attachments,
in addition to all other events related:
sent, delivery, failed reception, opening and clicks recorded - for emails.

To enable Registered Message in your account, please get in touch with our Customer Services team,
through the HELP separator in your e-goi interface, or simply call us.

If you supply custom data when sending (via API or SMTP),
every event returned via webhooks will contain the message related custom data.
The custom data in the webhook will be returned as it was supplied at the time of sending. An example follows.

For instance - if you send an Sms message (via API) using the arguments:

{ 
    "phone": "321-987654321", 
    "senderId": "2", 
    "message": "An Sms message (with full utf8 support 👍")", 
    "customData": "{\"meta-data\", \"my relevant metadata\"}" 
} 

You will receive events with the following data (example for the processed event):

[ 
    { 
        "data" : { 
            "recipientMobile" : "321-987654321", 
            "groupId" : 1, 
            "recipientId" : 4, 
            "senderMobile" : "321-987654321", 
            "messageId" : 1160, 
            "customData": "{\"meta-data\", \"my relevant metadata\"}" 
            "createDate" : 1453430810084 
        }, 
        "action" : "processed", 
        "actionDate" : 1453430810150 
    } 
] 

Templates are pre-defined messages that are used to ease message building and maintain coherence between topics and groups.
They are shared between multiple endpoint definitions and services (such as Multi-Channel or Alert)

Despite some differences in structure between channels, they have the subject and body already set, along with some options.

The Slingshot API enables the user to , should he choose to, create and execute advanced templates.These templates use the template engine JTWIG , both in template structure and code language. When creating a template , either for email or sms channels, you can use templates (for email you can use full html templates with CSS in them, in sms , standard sms message templates). When sending either an email or an sms, you can pass a JSON data structure within the parameter advancedTemplatingData.

Notes

See the section How To in order to see how to use the Slingshot API advanced template feature.

This section of Slingshot API advanced templating will demonstrate on how to use advanced templates in both email and sms. The aspects and code snippets below will demonstrate mostly common features and basic usage of advanced template.

The topics we will approach here will be the following:

• Basic Replacement
• Logic integration (If/else)
• Dynamic Replacement with Objects
• Iteration through objects

When creating a template (either for email or sms), for example, should you choose to use html or text, The following example represents an example where we want to replace the name value:

 
        "html" : "This is {{name.value}}"  
    

OR

 
        "text" : "This is {{name.value}}"  
    

When creating a payload to send a campaign (either via sms or email) the advancedTemplatingData payload attribute should contain:

 
        "advancedTemplatingData": { 
            "name": "Slingshot API" 
        } 
    

The result should be:

 
        This is Slingshot API 
    

When creating a template (either for email or sms), for example, should you choose to use html or text, The following example illustrates the usage of logic operators in advanced templates(if/else):

 
        "html" : "{% if flag == true %} True Value {% else %} False Value {% endif %}"  
    

OR

 
        "text" : "{% if flag == true %} True Value {% else %} False Value {% endif %}"   
    

When creating a payload to send a campaign (either via sms or email) the advancedTemplatingData payload attribute should contain:

 
        "advancedTemplatingData": { 
            "flag": false 
        } 
    

The result should be:

 
        False Value 
    

When creating a template (either for email or sms), for example, should you choose to use html or text, The following example uses a data structure in order to render it inside a template (if/else):

 
        "html" : "Item:{{item.text.value}} Description:{{item.description.value}} Price:{{item.price.value}}"  
    

OR

 
        "text" : "Item:{{item.text.value}} Description:{{item.description.value}} Price:{{item.price.value}}"   
    

When creating a payload to send a campaign (either via sms or email) the advancedTemplatingData payload attribute should contain:

 
       "advancedTemplatingData": { 
       "item": 
            { 
                "text": "Slingshot Cap", 
                "price": "4.95 euros", 
                "description" : "The new line of items from slingshot"  
            } 
    } 
    

The result should be:

 
        Item:Slingshot Cap 
        Description:The new line of items from slingshot 
        Price:4.95 euros 
    

When creating a template (either for email or sms), for example, should you choose to use html or text, The following example uses a data structure in order to render it inside a template (if/else):

 
        "html" : "{% for item in items %} Item:{{item.text.value}} Description:{{item.description.value}} Price:{{item.price.value}} {%endfor%}"   
    

OR

 
        "text": "{% for item in items %} Item:{{item.text.value}} Description:{{item.description.value}} Price:{{item.price.value}} {%endfor%}"   
    

When creating a payload to send a campaign (either via sms or email) the advancedTemplatingData payload attribute should contain:

 
       "advancedTemplatingData": { 
       "items": [ 
            { 
                "text": "Slingshot Cap", 
                "price": "4.95 euros", 
                "description" : "The new line of items from slingshot"  
            }, 
            { 
                "text": "Slingshot Shirt", 
                "price": "25.00 euros", 
                "description" : "The new line of items from slingshot"   
            }, 
            { 
                "text": "Slingshot Pin", 
                "price": "10.00 euros", 
                "description" : "The new line of items from slingshot"   
            } 
        ] 
    } 
    

The result should be:

 
        Item:Slingshot Cap
        Description:The new line of items from slingshot 
        Price:4.95 euros 
        Item:Slingshot Shirt 
        Description:The new line of items from slingshot 
        Price:25.00 euros 
        Item:Slingshot Pin 
        Description:The new line of items from slingshot 
        Price:10.00 euros 
    

For more information regarding on how to use JTWIG templating language, please see this guide.