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.

    1024 bits DKIM :
    Subdomain: mta._domainkey.{your-domain} Value : "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDh50JnspQbjA8gu9Q7togGADxpXmxSy3Q8MoMBkT16RGuMgad7eNmgS3lCrMB6ScN3EKmFbplk6aBOBJzA0NtQsTRZzBIrK61sBiAgzOn1w2sUC/GS26MslZhOiXNQFqPLDq3RUwediyyR7j29MCJXZ0rfjBDbnNgDmnmyf8LtkwIDAQAB"

    2048 bits DKIM :
    Subdomain: mta2048._domainkey.{your-domain} Value : "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6u1uEOvWyPBeU6qF3OXU1BgbQ6LMJKP47/8N1u4xIxLZ2D1NOW6RHWD+9t6M3xS5OtRlvHg483WvXQ7bSfmcPG+oXcSaGTRxaQ2QtSyStopl0VRJxxzpRrd4pFuViwb7Fq2Oj5ujpn2YQMg7BSlN+dSrma5cC7Gf7JtER9T0w94BMpZzacFP3svksXvpEroP0" "6LewCo+qzL4i+wkCuz/y5yx5R0tDUt4cziEaJ3nJ16VRoNrxwo2rzA210oc2sgAhL2GdcMQNxGc/s2FUZ1gQEbfNTBpKxJITqH+Reo/ZatV5ChMWRJnlTXEo0zj32erKdcTW3h/gvJ6ItA/JnEiIQIDAQAB"
  • 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.

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 allow you to personalise your messages (X-TM-SUB), include metadata (X-TM-META), add tags (X-TM-TAGS) or use 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

Copied !

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

HTTP success response code

Copied !
HTTP 200

Response body

Copied !
{"status":"success"}

Payload

Copied !

{  
    "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"}
    }
}

Fetch sending configuration

Retrieve current email sending configuration

HTTP request

GET

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

Header parameters

Parameter Description Required
x-apikey API Key Yes

Body Parameters

Parameter Description Required
trackOpens Activates opening tracking (bool) no
trackClicks Activates clicks tracking (bool) no
googleAnalytics Adds the Google UTM on urls in your email ( object : { enable (bool) , utmSource (string), utmContent (string), "utmCampaign (string), utmMedia (string) } ) no
unsubscribe Define a specific blacklist for your email (object : {enable (bool), blacklistId (string)} no

Errors

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

Curl

Copied !

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

HTTP success response

Copied !
HTTP 200

Payload

Copied !

{
  "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
}

Update sending configuration

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

Copied !

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

HTTP success response

Copied !
HTTP 200

Payload

Copied !

{
  "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

Copied !
{"status" : "status"}

List domains

List account domains

HTTP request

GET

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

Header parameters

Parameter Description Required
x-apikey API key Yes

Errors

HTML Code Error message Description
401 Not authorized Invalid credentials
400 Failure : An address for : \"to\" is not defined Wrong request
400 Bad request Wrong parameter(s) in your payload
500 Unable to retrieve domains Internal server error

Curl

Copied !

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

HTTP success response

Copied !
HTTP 200

Responses

Copied !

{
    "sending": "sending.abcdef.fr",
    "tracking": "tracking.abcdef.fr",
    "email": "email@abcdef.fr",
    "verifiedDkim": false,
    "verifiedSpf": false,
    "verifiedTracking": false,
    "verifiedMx": false,
    "verifiedA": false,
    "verifiedDomain": false
}

Add domains

Add domains for your acccount

HTTP request

POST

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

Header parameters

Parameter Description Required
x-apikey API key Yes

Body Parameters

Parameter Description Required
sending The sending domain you want to use (eg : subdomain.domain.com) Yes
tracking A sub domain of your sending domain (eg: links.domain.com). Must be on the same domain than your sending domain. Yes
email A valid email address (eg: jonh.doe@domain.com). Must be on the same domain than your sending domain. A validation email will be sent to this email address so be sure you are able to open an email on this mail box. Yes
dkim2048 A boolean to activate a 2048 bits encrypted key for the DKIM of the linked domain No

Errors

HTML Code Error message Description
401 Not authorized Invalid credentials
400 Failure : An address for : \"to\" is not defined Wrong request
400 Bad request Wrong parameter(s) in your payload
500 Unable to retrieve domains Internal server error

Curl

Copied !


curl -X POST -d '{"sending": "sending.abcdef.fr", "tracking": "tracking.abcdef.fr","email": "email@abcdef.fr"}' -H "Content-Type:application/json" -H "x-apikey : YOUR_API_KEY" https://api.sarbacane.com/v1/sendkit/email/domains

HTTP success response

Copied !
HTTP 200

Responses

Copied !

{
    "sending": "sending.abcdef.fr",
    "tracking": "tracking.abcdef.fr",
    "email": "email@abcdef.fr",
    "verifiedDkim": false,
    "verifiedSpf": false,
    "verifiedTracking": false,
    "verifiedMx": false,
    "verifiedA": false,
    "verifiedDomain": false
}

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

Body Parameters

Parameter Description Required
blacklist Blacklist's type no
listname Name of the list no

URL parameters

Parameter Description Required
type Blacklist type, possible values : bounces, unsubscribes, complaints yes
email Email of the recipient you are searching for yes

Errors

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

Curl

Copied !

curl -X GET -H "x-apikey:YOUR_API_KEY" https://api.sarbacane.com/sendkit/email/blacklists/{type}/{email}

HTTP success response code

Copied !
200

Response body

Copied !

{
    "email": "aaa@aaa.fr",
    "blacklist": "unsubscribers",
    "listName": "sample list",
    "createdDate": "2023-11-22T16:38:02.189+00:00",
    "lastModifiedDate": "2023-11-22T16:38:02.189+00:00"
}

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

Copied !

curl --request POST 'https://api.sarbacane.com/sendkit/email/blacklists/' \
  --header 'content-type: application/json' \
  --header 'x-apikey: YOUR_API_KEY' \
  --data '{
	"type": "unsubscribes",
	"email": "test@test.com",
  "list": "Newsletter"
}'

HTTP success response code

Copied !
200

Response body

Copied !
{
    "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

Copied !

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

Copied !
200

Body of response

Copied !

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

Payload

Copied !

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

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

Copied !

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

HTTP success response

Copied !
204

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

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

Copied !

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"}' \
   https://api.sarbacane.com/sendkit/sms/send/notification

HTTP success response code

Copied !
HTTP 200

Response body

Copied !
{"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

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

Copied !

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

Copied !
HTTP 200

Response body

Copied !
{"creditsUsed": 1.00}

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

Copied !
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

Copied !
HTTP 200

Response body

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

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

Copied !

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

Copied !
HTTP 200

Response body

Copied !

  {
    "id": "91a4dF6DeF2AdbaD62c8BXXX"
  }

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

Copied !

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

Copied !
HTTP 204

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

Copied !
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

Copied !
HTTP 200

Response body

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

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

Copied !

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

Copied !
HTTP 200

Response body

Copied !

  {
    "id": "91a4dF6DeF2AdbaD62c8BE34"
  }

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

Copied !
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

Copied !
HTTP 204