Sendkit – Sarbacane – Documentation API

Introduction

Our API allow you to manage your Sendkit account from your application, website or infrastructure. You can retrieve your data, send emails or set up your Sendkit account without connecting to the Sendkit interface.

Sendkit's APIs have been developed with HTTP standards and RESTful terminology.

To help you use our API, we have published libraries for the most popular programming languages. You can use them, modify them according to your needs or make direct CURL calls.

For each call, you can find code examples about the parameters to pass and those returned.

Domains

Sarbacane invites you to set up the domain name of the sending server, as well as all the links included in your campaigns, with your own name. This personalization will improve the deliverability of your emails and increase your open and click rates, by providing links that are more reassuring for your readers.

Setting up your DKIM
DKIM is a cryptographic protocol that prevents spammers from using your domain name to send illegitimate emails. DKIM is composed of a subdomain and a key. You need to add data to your domain name host by adding a TXT record.
Subdomain: mta._domainkey.{your-domain}
Value : v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3...
Defining SPF
The SPF allows the domain name owner to authorize a list of servers to send emails on its behalf. The SPF is composed of an SPF record. You need to add this information to the existing SPF record, or create a new one.
Domain or sub-domain: {your-domain}
Value: v=spf1 include:spf.tipimail.com -all
Customize your tracking domain
The tracking domain allows you to personalize your tracked links contained in the email with a dedicated domain. To use a tracking domain, you need to add a CNAME record composed of a sub-domain and the redirection
Subdomain to customize your link: {subDomain.your-domain}
Value: link.domaincustom.net.
Having a MX record
Internet service providers and other email providers have specific requirements for validating the legitimacy of a domain name. You need to make sure that your domain name meets these requirements to ensure the best possible deliverability of your emails, especially when it comes to MX records. An MX record (for Mail eXchanger) is a type of Domain Name System (DNS) record that associates a domain name with an email server. It is used to receive emails sent to an email address using your domain name. The presence of one or more records is necessary to prove the legitimacy of your domain name..
Having a A record
The DNS A record connects a name (usually the physical name of a server) with an IP address. Each mail server must also have an A resource record. This enables the mail server to be connected to the corresponding IP address.

Update sending configuration

HTTP request

POST

https://api.sarbacane.com/sendkit/email/settings

Header parameters

Parameter	Description	Required
x-apikey	API key	Yes

Errors

HTML Code	Error message	Description
400	Unable to retrieve sending configuration	Bad request
500	Unable to retrieve sending configuration	Internal server error

Curl


curl -X GET -H "Content-Type: application/json" -H "x-apikey:YOUR_APIKEY" https://api.sarbacane.com/v1/sendkit/email/settings

HTTP success response

HTTP 200

Payload


{
  "trackOpens": true,
  "trackMailTo": true,
  "googleAnalytics": {
    "utmSource": "utmSource",
    "enable": true,
    "utmContent": "utmContent",
    "utmCampaign": "utmCampaign",
    "utmMedia": "utmMedia"
  },
  "unsubscribe": {
    "enable": true,
    "blacklistId": "5d63f57f933298167f46a433",
    "content": "content"
  },
  "customTrack": {
    "enable": true,
    "customs": [
      {
        "value": "value",
        "key": "key"
      },
      {
        "value": "value",
        "key": "key"
      }
    ]
  },
  "id": "5d63f57f933298167f46a433",
  "addNewDomains": true,
  "trackClicks": true
}

Response

{"status" : "status"}

Fetch sending configuration

Retrieve current email sending configuration

HTTP request

GET

https://sarbacaneapis.com/v1/sendkit/email/settings

Header parameters

Parameter	Description	Required
x-apikey	API Key	Yes

Errors

HTML Code	Error message	Description
400	Unable to retrieve sending configuration	Bad request
500	Unable to retrieve sending configuration	Internal server error

Curl


curl -X GET -H "Content-Type: application/json" -H "x-apikey:YOUR_APIKEY" https://api.sarbacane.com/v1/sendkit/email/settings

HTTP success response

HTTP 200

Payload


{
  "trackOpens": true,
  "trackMailTo": true,
  "googleAnalytics": {
    "utmSource": "utmSource",
    "enable": true,
    "utmContent": "utmContent",
    "utmCampaign": "utmCampaign",
    "utmMedia": "utmMedia"
  },
  "unsubscribe": {
    "enable": true,
    "blacklistId": "5d63f57f9e698167f46a433",
    "content": "content"
  },
  "customTrack": {
    "enable": true,
    "customs": [
      {
        "value": "value",
        "key": "key"
      },
      {
        "value": "value",
        "key": "key"
      }
    ]
  },
  "id": "5d63f57f9r598167f46a433",
  "addNewDomains": true,
  "trackClicks": true
}

Delete email from blacklist

Deleting email address from blacklist

HTTP request

DELETE

https://api.sarbacane.com/sendkit/email/blacklists/unsubscribes/{email}

Header parameters

Parameter	Description	Required
x-apiKey	API Key	Yes

Errors

HTML Code	Error message	Description
401	Not authorized	Invalid or missing key
404	Not found	Email not found
204	No content	Successfully deleted unsubscribe email
500	Unable to delete unsubscribe email	Internal server error

Curl


curl --location -request DELETE 'https://api.sarbacane.com/sendkit/email/blacklists/unsubscribers/{email}' \
--header 'x-apikey:YOUR_API_KEY'

HTTP success response

Fetch email from blacklist

Retrieve email address information from blacklist

HTTP request

GET

https://api.sarbacane.com/sendkit/email/blacklists/{type}/{email}

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

URL parameters

Parameter	Description	Required
type	Blacklist type, possible values : bounces, unsubscribes, complaints	No

Errors

HTML Code	Error message	Description
401	Not authorized	Missing API key or incorrect credentials
400	Bad requuest	Wrong value in your request

Curl


curl -X GET -H "Content-Type: application/json" -H "x-apikey:YOUR_SMTP_USERNAME" -H "x-apikey:YOUR_SMTP_KEY" https://api.sarbacane.com/sendkit/email/blacklists/{type}/{email}

HTTP success response code

Response body

{
    "email": "email@example.com",
    "date": 1438765958,
    "blacklist": "bounces"
}

Add email into a blacklist

Adding an email address into a blacklist

HTTP request

POST

https://api.sarbacane.com/sendkit/email/blacklists

Header parameters

Parameter	Description	Required
x-apikey	API key	Yes

Body Parameters

Parameter	Description	Required
type	Blackist type, possible values : bounces, unsubscribes, complaints	Yes
email	Email address to add	Yes

Errors

HTML Code	Error message	Description
200	Success	Email address added in your blacklist
401	Not authorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request

Curl


curl -d '{"page":1,"pageSize":10}' -H "Content-Type: application/json" -H "x-apikey:YOUR_SMTP_USERNAME" -H "x-apikey:YOUR_KEY" https://api.sarbacane.com/sendkit/email/blacklists

HTTP success response code

Response body

{
    "type": "bounces",
    "email": "email@example.com"
}

List blacklisted emails

Allows you to list email addresses from your blacklists

HTTP request

POST

https://api.sarbacane.com/sendkit/email/blacklists/list

Header parameters

Parameter	Description	Required
x-apikey	API Key	oui

Body Parameters

Parameter	Description	Required
type	Type of the blacklist you would like to see. Possible values: bounces, unsubscribes, complaints	Yes
list	Available for customized blacklists like "unsubscribes", and "complaints". By default, all unsubscribes or complaints will be returned.	No
pageSize	Number of items to return	No
page	Page number	No
order	Return order (0 (ASC) or 1 (DESC) / based on the date the email was added)	No

Errors

HTML Code	Error message	Description
401	Not authorized	The API key is not valid or is missing
400	Bad request	Incorrect value included in your request

Curl


curl -d '{"page":1,"pageSize":10}' -H "Content-Type: application/json" -H "x-apikey:YOUR_SMTP_USERNAME" -H "x-apikey:YOUR_KEY" https://api.sarbacane.com/sendkit/email/blacklists/list

HTTP success response code

Body of response


{
    "bounces": [
        {
            "email": "email1@example.com",
            "date": 1438765958,
            "reason": ""
        },
        {
            "email": "email2@example.com",
            "date": 1438765958,
            "reason": ""
        }
    ],
    "total": 200
}

Payload


{
    "type" : "unsubscribes",
    "list" : "my custom blacklist",
    "pageSize": 10,
    "page": 1,
    "order": 1
}

Send a transactional email

Sending a transactional email

HTTP request

POST

https://api.sarbacane.com/sendkit/email/send

Header parameters

Parameter	Description	Required
x-apikey	API key	Yes

Body Parameters

Parameter	Description	Required
to	Array of recipient parameters : email address (email) and a name (personnalName)	Yes
msg	Object of email elements : sending email address (from), subject (subject), html version of the message (html) and his text version(text)	Yes
headers	Optional : headers allows to personalize your sending (X-TM-SUB), including metadata (X-TM-META), adding tags (X-TM-TAGS) or using a template (X-TM-TEMPLATE)	No

Errors

HTML Code	Error message	Description
401	Not authorized	Invalid credentials
400	Failure : An address for : \"to\" is not defined	Recipient email address is not defined
400	Bad request	Wrong parameter(s) in your payload

Curl


curl -X POST -d '{"to":[{"address":"to@example.com"}], "msg":{"from":{"address":"from@example.com"},"subject":"My subject","html":"Html message","text":"Text message"},"apikey":"YOUR_API_KEY"}' -H "Content-Type:application/json" -H "x-apikey : YOUR_API_KEY" https://api.sarbacane.com/sendkit/email/send

HTTP success response code

HTTP 200

Response body

{"status":"success"}

Payload


{  
    "to": [{"address":"recipient@email.com", "personalName":"Recipient Name"}],
    "msg": {
        "from": {"personalName": "Sender Name","address": "sender@email.com"},
        "subject": "Subject",
        "text": "text version",
        "html": "html version"
    },
    "headers"  : {
         "X-TM-SUB" : [{
         "email" : "recipient@email.com",
    		   "values" : {"firstName" : "{firstname}", "orderId" : "{orderId}"} 
    		}],
          "X-TM-TEMPLATE" : "template-name",
          "X-TM-TAGS" : ["resetPassword", "welcome", "orderConfirmation"],
          "X-TM-META" : {"recipientId":"123456789","shipment_id":"123456789"}
    }
}

Send SMS notification

Send a notification per SMS

HTTP request

POST

https://api.sarbacane.com/sendkit/sms/send/notification

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

Body Parameters

Parameter	Description	Required
number	Recipient of the SMS	Yes
message	Message content: "Confirmation code: 283951". Allowed characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789@Â£_!$"#èé%Ã¹&Ã¬Ã²()*:+;,<-=Ã'Ã±Ã....>ÃœÃ¼Ã¥é/?à\|^Â¤{}~\'	Yes
sender	Personalized sender of the message: "YourCompany". Without personalization, the sender will be a numeric short code like XX XXX. If you personalize the sender, it must contain between 3 and 11 ALPHANUMERIC characters.	No
campaignName	The name of your message pool: "Confirmation code". This parameter is used to group several messages together in the same pool, to obtain global statistics on these messages.	No
category	The Tag of your message pool: "codeConfirmation". This Tag is the search key for your messages. Use it in your various queries: stats, blacklists, callbacks...	No
date	"date": 1398177000000 => Tue, 22 Apr 2014 14:30:00 GMT Scheduling the campaign for a specific date (format: timestamp milliseconds). Please note that for messages sent to France, notification is not subject to the sending times required for marketing/commercial messages.	No

Errors

HTML Code	Error message	Description
200		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request
500	Internal error	The sending request was not processed due to an internal error.

Curl


curl -X POST \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"number":"+33600000000","message":"Code de confirmation: 283951","sender":"YourCompany","campaignName":"Code de confirmation","category":"codeConfirmation","date": 1398177000000}' \
   https://api.sarbacane.com/sendkit/sms/send/notification

HTTP success response code

HTTP 200

Response body

{"creditsUsed": 1.00}

Send a unit marketing SMS

Send a single marketing message

HTTP request

POST

https://api.sarbacane.com/sendkit/sms/send/marketing

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

Body Parameters

Parameter	Description	Required
number	Recipient of the message	Yes
message	Message content: "Confirmation code: 283951". Allowed characters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789@Â£_!$"#èé%Ã¹&Ã¬Ã²()*:+;,<-=Ã'Ã±Ã....>ÃœÃ¼Ã¥é/?à\|^Â¤{}~\'	Yes
sender	Personalized sender of the message: "YourCompany". Without personalization, the sender will be a numeric short code like XX XXX. If you personalize the sender, it must contain between 3 and 11 ALPHANUMERIC characters.	No
campaignName	The name of your message pool: "Confirmation code". This parameter is used to group several messages together in the same pool, to obtain global statistics on these messages.	No
category	The Tag of your message pool: "codeConfirmation". This Tag is the search key for your messages. Use it in your various queries: stats, blacklists, callbacks...	No
date	"date": 1398177000000 => Tue, 22 Apr 2014 14:30:00 GMT Scheduling the campaign for a specific date (format: timestamp milliseconds). Please note that for messages sent to France, notification is not subject to the sending times required for marketing/commercial messages.	No

Errors

HTML Code	Error message	Description
200		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentialstes
400	Bad request	Wrong value in your request
500	Internal error	The sending request was not processed due to an internal error.

Curl


curl -X POST \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"number":"+33600000000","message":"Code de confirmation: 283951","sender":"YourCompany","campaignName":"Code de confirmation","category":"codeConfirmation","date": 1398177000000}' \
   https://api.sarbacane.com/sendkit/sms/send/marketing

HTTP success response code

HTTP 200

Response body

{"creditsUsed": 1.00}

Add a SMS unsubscriber

Add the phone number of a contact unsubscribing by SMS to the blacklist

HTTP request

POST

https://api.sarbacane.com/sendkit/sms/blacklists/unsubscribers

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

Body Parameters

Parameter	Description	Required
identifier	Phone number	Yes

Errors

HTML Code	Error message	Description
200		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request
500	Internal error	The sending request was not processed due to an internal error.

Curl


curl -X POST \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -D '{ "identifier": "+33600000000" }
   https://api.sarbacane.com/sendkit/sms/blacklists/unsubscribers

HTTP success response code

HTTP 200

Response body


  {
    "id": "91a4dF6DeF2AdbaD62c8BXXX"
  }

Get SMS unsubscribers

Get the list of sms unsubscribers

HTTP request

GET

https://api.sarbacane.com/sendkit/sms/blacklists/unsubscribers

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

Errors

HTML Code	Error message	Description
200		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request
500	Internal server error	The sending request was not processed due to an internal error.

Curl

curl -X POST \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   https://api.sarbacane.com/sendkit/sms/blacklists/unsubscribers

HTTP success response code

HTTP 200

Response body

[
  {
    "id": "91a4dF6DeF2AdbaD62c8BE38",
    "deleted": false,
    "createdAt": "1684151350797",
    "lastUpdate": "1684151350797",
    "identifier": "+33600000000",
    "blacklistId": "175eBD3e39eE278FEf9d6698"
  },
  {
    "id": "8a5bDce7bEFbB883Cf82a432",
    "deleted": false,
    "createdAt": "1684151350797",
    "lastUpdate": "1684151350797",
    "identifier": "+33600000000",
    "blacklistId": "175eBD3e39eE278FEf9d6698"
  }
]

Delete a SMS unsubscriber

Delete the phone number of a contact who has unsubscribed by SMS

HTTP request

DELETE

https://api.sarbacane.com/sendkit/sms/blacklists/unsubscribers

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

URL parameters

Parameter	Description	Required
identifier	Phone number	Yes

Errors

HTML Code	Error message	Description
204		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request
500	Internal error	The sending request was not processed due to an internal error

Curl


curl -X DELETE \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \   
   https:api.sarbacane.com/sendkit/sms/blacklists/unsubscribers?identifier=phoneNumber

HTTP success response code

HTTP 204

Add a SMS bounce

Add a phone number to the SMS bounces blacklist

HTTP request

POST

https://api.sarbacane.com/sendkit/sms/blacklists/bounces

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

Body Parameters

Parameter	Description	Required
identifier	Phone number	Yes

Errors

HTML Code	Error message	Description
200		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request
500	Internal error	The sending request was not processed due to an internal error.

Curl


curl -X POST \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -D '{ "identifier": "+33600000000" }
   https://api.sarbacane.com/sendkit/sms/blacklists/bounces

HTTP success response code

HTTP 200

Response body


  {
    "id": "91a4dF6DeF2AdbaD62c8BE34"
  }

Get SMS bounces

Get the SMS bounces list

HTTP request

GET

https://api.sarbacane.com/sendkit/sms/blacklists/bounces

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

Errors

HTML Code	Error message	Description
200		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request
500	Internal error	The sending request was not processed due to an internal error

Curl

curl -X POST \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   https://api.sarbacane.com/sendkit/sms/blacklists/bounces

HTTP success response code

HTTP 200

Response body

[
  {
    "id": "91a4dF6DeF2AdbaD62c8BE38",
    "deleted": false,
    "createdAt": "1684151350797",
    "lastUpdate": "1684151350797",
    "identifier": "+33600000000",
    "blacklistId": "175eBD3e39eE278FEf9d6698"
  },
  {
    "id": "8a5bDce7bEFbB883Cf82a432",
    "deleted": false,
    "createdAt": "1684151350797",
    "lastUpdate": "1684151350797",
    "identifier": "+33600000000",
    "blacklistId": "175eBD3e39eE278FEf9d6698"
  }
]

Delete a SMS bounce

Remove a contact's phone number from the SMS bounce list

HTTP request

DELETE

https://api.sarbacane.com/sendkit/sms/blacklists/bounces

Header parameters

Parameter	Description	Required
x-apiKey	API key	Yes

URL parameters

Parameter	Description	Required
identifier	Phone number	Yes

Errors

HTML Code	Error message	Description
204		Request successfully processed
401	Unauthorized	Missing API key or incorrect credentials
400	Bad request	Wrong value in your request
500	Internal error	The sending request was not processed due to an internal error.

Curl

curl -X DELETE \
   -H "x-apiKey: YOUR_API_KEY" \
   -H "Content-Type: application/json" \   
   https:api.sarbacane.com/sendkit/sms/blacklists/bounces?identifier=phoneNumber

HTTP success response code

HTTP 204