This is our new version of API. If you want to use the old version of API: Transactional v1
Use Cases Integrations
Transactional API

Transactional API (V2)

Introduction

Introduction

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)

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

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

SDKs

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.

SMTP

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:

Parameter Description Definition/Example
Mail Server the address of the smtp server bo51.e-goi.com
Port the port to connect to the smtp 1587
Connection Security the security type STARTTLS
Authentication Method the authentication method password
User Name the user name egoi@example.com

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!"; 
} 

Authentication

ApiKey

You will need to have an account in E-goi app, and produce an ApiKey by clicking on your username (top right corner) and selecting integrations.

Then there are two ways to activate the API Usage:

  • E-goi app - go to Reports (on top) and select Transactional.
  • API Request - call the API method Enable API usage (in Utilities).

The ApiKey will regulate the actions of the user, depending of its agreement with E-goi.

The ApiKey is necessary for a number of methods, so make sure you have a valid Api Key.;

Security Scheme Type API Key
Header parameter name: ApiKey

Alerts

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.

states

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

states

State Description Is Final?
pending The Alert has been activated, and its awaiting recipient input No
acknowledge The Alert was responded by a recipient Yes
noaction The Alert was not responded by a recipient, having reached the Max Attempts Yes
cancelack The Alert was canceled by the sender Yes;

Get Single Alert Template

This method returns the Alert Template wih the id in the path

Authorizations:
path Parameters
id
required
string
Example: 1234

The id of the Alert Template

Responses

Request samples

curl --location --max-time 30 --request GET 'slingshot.egoiapp.com/api/v2/alert/template/<string>' \
--header 'ApiKey: '

Response samples

Content type
application/json
{
  • "alertId": 1,
  • "name": "Alert1.",
  • "templateId": "2",
  • "channel": "sms,email,push",
  • "interval": 3600,
  • "maxAttempts": 1
}

Remove An Alert Template

This method removes an Alert Template from the system

Authorizations:
path Parameters
id
required
string
Example: 1234

The id of the Alert Template to remove

Responses

Request samples

curl --location --max-time 30 --request DELETE 'slingshot.egoiapp.com/api/v2/alert/template/<string>' \
--header 'ApiKey: '

Response samples

Content type
application/json
{}

Update Single Alert Template

This method will change information about the template

Authorizations:
path Parameters
id
required
string
Example: 1234

The id of the Alert Template to edit

Request Body schema: */*
name
string

Text Identifier for the template.

templateId
string

Template used to create the alert.

channel
string

Channel to where the alert template belongs to.

interval
integer <int64>

The interval in seconds between messages to the recipient(s). Maximum interval is 86400 seconds (24 hours).

maxAttempts
integer <int64>

The maximum amount of attempts to be made.

Responses

Request samples

curl --location --max-time 30 --request PATCH 'slingshot.egoiapp.com/api/v2/alert/template/<string>' \
--header 'ApiKey: ' \
--header 'Content-Type: */*' \
--data-raw '{"name":"<string>","templateId":"<string>","channel":"<string>","interval":"<long>","maxAttempts":"<long>"}'

Execute Alert

This method executes an alert flow , using a pre-created alert template.

Authorizations:
Request Body schema: application/json

default response

One of
alertTemplateName
required
string

the name of the alert template to use. Already has to exist in the system.

senderId
required
string

the id to identify the sender.

required
Array of objects (ToEmailAlertObject) [ items ]

a list of recipients of the alert.

Responses

Request samples

Content type
application/json
Example
{
  • "alertTemplateName": "welcome",
  • "senderId": "1234",
  • "to": [
    ]
}

Response samples

Content type
application/json
{
  • "alertId": "1234"
}

Stop Alert

This method will stop any alerts that are being processed

Authorizations:
Request Body schema: application/json
alertName
string

The name of the Request.

Responses

Request samples

Content type
application/json
{
  • "alertName": "1234"
}

Response samples

Content type
application/json
{
  • "alertId": "1234"
}

Get All Alert Templates

This method returns all the Alert Templates

Authorizations:

Responses