API Trigger

This post is also available in: Czech

API triggers are designed for e-mail real time sending triggered by calling Samba API from the client side. They can be utilized, for example, to send special offer to customer immediately after his or her registration or any other action.

API Trigger in Samba

  • E-mail is sent immediately after your API call, regardless of whether the e-mail address is currently in your database.
  • You can use static or personalised template with up to 10 personalised products (if there is any customer with the called e-mail address in your customer database, personalised products are affected by his or her purchase history)
  • API call accepts any customer parameter key+value, which you would like to display in the e-mail template.

Create campaign

  1. In the menu, select API Trigger and click on + New Campaign.  
  2. Campaign settings

    Name
     – it has to be the same as campaignName in API request.
    Personalisation – filtering personalised products by Samba using standard product parameters
    Email – subject, mirror text (second subject), UTM
    Template – only Segmentation and Personalised types of template are supported.
    • The template can contain any customer parameter, which you would like to display.
    • Use the parameters in the following format:
       {{customer_custom_param_*yourParameter*}}

      where *yourParameter* can contain alphanumeric characters (A-Z+a-z+0-9, case-sensitive)

    • If your API call does not include the parameter (or its value is an empty string) used in a template, nothing will be displayed at the place
    • You can create IF/ELSE blocks using Mustache.js syntax (https://mustache.github.io/mustache.5.html), e.g.
      {{#customer_custom_param_product2Title}}
         This part of the template will be displayed, if the API call includes parameter "product2Title" and its value is not an empty string
      {{/customer_custom_param_product2Title}}
      
      {{^customer_custom_param_product2Title}}   
         This part of the template will be displayed, if the API call does not include parameter "product2Title" or its value is an empty string
      {{/customer_custom_param_product2Title}}
  3. Click on Confirm to confirm your changes or discard them by clicking on Cancel.
  4. Enable the campaign
    If you edit already running campaign, it will not be disabled after clicking on Confirm. (unlike any other campaign in Samba)
  5. E-mail is sent immediately after your API call if the API trigger campaign with corresponding Name is enabled.

How does API Trigger call work?

Endpoint URL

Depending on your account, select the appropriate endpoint URL.

  • If you are logging in at app.samba.ai –> choose the URL api.samba.ai
  • If you are logging in at enterprise.samba.ai –> choose the URL api.yottly.com

Your account ID can be found in the Settings section as part of your unique tracking script.

POST
https://api.samba.ai/shop/XX/send-trigger-mail
header: X-Api-Key: your-api-key
{
  "email": "foo@bar.com",
  "campaignName": "Triggered Campaign",
  "customCustomerParameters": {
"parameter1name": "parameter1value",
"parameter2name": "parameter2value"
   }
}
  • xx – Samba ID of your eshop
  • your-api-key – Samba API key for your eshop (Please ask us for the API key via email)
  • email – the e-mail address on which you want to send the e-mail
  • campaignName – the name of the campaign corresponding to the campaign name in Samba
  • customCustomerParameters – optional, key-value pairs
  • parameter1name – the name of the parameter whose value you would like to display in an e-mail template
    • can contain only alphanumeric characters (A-Z+a-z+0-9,case-sensitive)
  • parameter1value – the value of the parameter which you would like to display in an e-mail template
    • If you do not know the value for an API call, do not use this parameter or use an empty string as the value

 

Example

curl -H 'X-Api-Key:your-api-key' -d '{"email": "foo@bar.com","campaignName": "Triggered Campaign"}' https://api.samba.ai/shop/XX/send-trigger-mail

Response

  • success
    • HTTP 200 { “status”: “ok”}
  • invalid input
    • HTTP 200 { “status”: “error”, “error”: “invalidInput” }
    • HTTP 200 { “status”: “error”, “error”: “noSuchCampaign” }
    • HTTP 200 { “status”: “error”, “error”: “campaignDisabled” }
  • error
    • HTTP 4xx
    • HTTP 5xx

This post is also available in: Czech

Updated on January 5, 2024

Was this article helpful?

Related Articles