Contacts – Sarbacane – Documentation API

Add a webhook

Allows to create an webhook subscription

HTTP request

POST

https://api.sarbacane.com/v1/webhooks

Header parameters

Parameter	Description	Required
accountID	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
url	A valid https url (must be valid and https^)	yes
displayName	A display name of your webhook subscription	yes
kinds	An array with theses possibles following values : FORM_SUBMIT, HARD_BOUNCE, SOFT_BOUNCE, SUCCESSFUL, CAPTCHA, COMPLAINT, OPEN, HIT, UNSUBSCRIBE	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
400	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication


curl -X POST "https://api.sarbacane.com/v1/webhooks"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"url":"https://help.sarbacane.com/suite/","displayName":"webhook description","kinds":["HARD_BOUNCE", "FORM_SUBMIT"]}'

HTTP Headers Authentication


curl -X POST "https://api.sarbacane.com/v1/webhooks"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"url":"https://help.sarbacane.com/suite/","displayName":"webhook description","kinds":["HARD_BOUNCE", "FORM_SUBMIT"]}'

HTTP success response code

HTTP/2 200

Get Webhooks

Allows to get all webhook subscriptions

HTTP request

GET

https://api.sarbacane.com/v1/webhooks

Header parameters

Parameter	Description	Required
accountID	Account ID	yes
apiKey	API key	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
400	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body


[
 {
  "id":"webhookId",
  "accountId":"accountid",
  "displayName":"description",
  "url":"https://webhook.site/www-xxx-yyy-zzz",
  "kinds":["HARD_BOUNCE","SOFT_BOUNCE","SUCCESSFUL","CAPTCHA","COMPLAINT","OPEN","HIT","UNSUBSCRIBE"],
  "creationDate":"2025-04-23T13:54:26.938Z"
  },
  {...},
  {...}
]

Get Webhook

Allows to get a specific webhook

HTTP request

GET

https://api.sarbacane.com/v1/webhooks/{webhookId}

Header parameters

Parameter	Description	Required
accountID	Account ID	yes
apiKey	API key	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
400	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks/{webhookId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks/{webhookId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body


 {
  "id":"webhookId",
  "accountId":"accountid",
  "displayName":"description",
  "url":"https://webhook.site/www-xxx-yyy-zzz",
  "kinds":["HARD_BOUNCE","SOFT_BOUNCE","SUCCESSFUL","CAPTCHA","COMPLAINT","OPEN","HIT","UNSUBSCRIBE"],
  "creationDate":"2025-04-23T13:54:26.938Z"
  }

Webhooks’ responses

According to your different webhooks subscriptions, you may receive different JSON structures. Here bellow our JSON envelopes :

DELIVERED
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"date": "2025-05-05T09:26:15.557Z",
"type": "delivered",
"ID": "{webhookId}",
"State": "{campaignType}",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

OPEN
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"latitude": 48.8582,
"longitude": 2.3387,
"region": "EU",
"operatingSystem": "recipient OS",
"language": "recipient language",
"browser": "FIREFOX11 11.0",
"webmail": "webmail",
"date": "2025-05-05T09:29:59.499Z",
"type": "open",
"ID": "recipientId",
"State": "campaignType",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

CLICK
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"latitude": 48.8582,
"longitude": 2.3387,
"country": "FR",
"region": "EU",
"operatingSystem": "WINDOWS_10",
"language": "en-US",
"browser": "CHROME10 107.0.0.0",
"webmail": "Unknown",
"url": "https://www.url.com?utm_source=Sarbacane&utm_medium=email&utm_campaign=((CampaignName))",
"date": "2025-05-05T09:32:52.704Z",
"type": "click",
"ID": "recipientId",
"State": "NORMAL",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

UNSUBSCRIBE
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"latitude": 48.8709,
"longitude": 2.3561,
"country": "FR",
"region": "EU",
"city": "Paris",
"postcode": "75010",
"operatingSystem": "WINDOWS_10",
"language": "fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7",
"browser": "CHROME13 136.0.0.0",
"webmail": "Unknown",
"date": "2025-05-05T12:27:16.354Z",
"type": "unsubscribe",
"ID": "{contactId}",
"State": "NORMAL",
"Origin Kind": "LIST",
"Origin Caption": "origin",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": "MANUAL"
}

HARDBOUNCE
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"smtpDescription": "failed to find ip addr",
"category": "BAD_DOMAIN",
"returnCode": 505,
"date": "2025-05-05T12:34:50.631680671Z",
"type": "hard_bounce",
"ID": "recipientId",
"State": "NORMAL",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

FORM SUBMIT
{
"fieldId-1": "data",
"fieldId-2": "data",
"EMAIL": "recipient@sarbacane.com",
"PHONE": "phone number",
"fieldId-3": "3",
"formId": "formId",
"formName": "form name",
"listId": "listId"
}

Get all lists

Allow you to get all available contacts lists

HTTP request

GET

https://sarbacaneapis.com/v1/lists

Header parameters

Parameter	Description	Required
accountId	Account Id	Yes
apiKey	Api key	Yes

URL parameters

Parameter	Description	Required
offset	Offset position	No
limit	Limit the number of results - Max : 1000	No

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target is already in use by another ressource
500	INTERNAL_SERVER_ERROR	Internal server issue, please contact our support

HTTP authentification

curl -X GET "https://sarbacaneapis.com/v1/lists?offset=0&limit=3" 
    -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers authentification

curl -X GET "https://sarbacaneapis.com/v1/lists?offset=0&limit=3" 
    -H "accountId: YOUR_ACCOUNTID
    -H "apiKey: YOUR_API_KEY"

Success HTTP response

HTTP/2 200

Response body

[
    {
        "count": 20000,
        "created": "2017-08-24T14:59:36Z",
        "customFields": null,
        "edited": "2017-08-24T15:00:56Z",
        "id": "z2P3eXaMQUq9-kIL3wV1Cg",
        "kind": "NORMAL",
        "name": "Exemple: 200 000"
    },
    {
        "count": 1,
        "created": "2017-08-30T10:24:50Z",
        "customFields": null,
        "edited": "2017-08-30T10:26:14Z",
        "id": "eT060sIaSPee0dAYqBiL8A",
        "kind": "NORMAL",
        "name": "Exemple: api list"
    },
    
]

Add a list

Allows you to create a list of contacts.

HTTP request

POST

https://sarbacaneapis.com/v1/lists

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
name	List name	yes
teams	Table containing group ids to be related to the list	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/lists"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"name": "API List"}'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/lists"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"name": "API List"}'

HTTP success response code

HTTP/2 200

Response body

{
    "count": 0,
    "created": "2017-10-02T08:26:10Z",
    "customFields": null,
    "edited": "2017-10-02T08:26:10Z",
    "id": "AhjmGK9YRlGbXKawl1pBvw",
    "kind": "NORMAL",
    "name": "API List"
}

Edit a list

HTTP request

PUT

https://sarbacaneapis.com/v1/lists/{listId}

Header parameters

Parameter	Description	Required
accountId	Account Id	Yes
apiKey	Api key	Yes

HTTP Authentification

curl -X POST "https://sarbacaneapis.com/v1/lists"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"name": "API List"}'

Response body

{
    "count": 0,
    "created": "2017-10-02T08:26:10Z",
    "customFields": null,
    "edited": "2017-10-02T08:26:10Z",
    "id": "AhjmGK9YRlGbXKawl1pBvw",
    "kind": "NORMAL",
    "name": "API List"
}

Empty a list

Allows you to empty a list of contacts.

HTTP request

POST

https://sarbacaneapis.com/v1/lists/{listId}/empty

Header parameters

Parameter	Description	Required
accountId	Accout ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
listId	List ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/empty"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/empty"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

Delete a list

Allows you to delete a list of contacts.

HTTP request

DELETE

https://sarbacaneapis.com/v1/lists/{listId}

Header parameters

Parameter	Description	Required
accountId	Account Id	Yes

URL parameters

Parameter	Description	Required
listId	List Id	Yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	Missing account Id in the request
401	NEED_API_KEY	Missing API key in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	Service in not available
500	FAILED TO ACQUIRE LOCK	Target is already in use by another ressource
500	INTERNAL_SERVER_ERROR	Internal server issue, please contact our support

HTTP Authentification

curl -X DELETE "https://sarbacaneapis.com/v1/lists/{listId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers authentification

curl -X DELETE "https://sarbacaneapis.com/v1/lists/{listId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

Success HTTP response

HTTP/2 200

List groups related to a list

Allows you to retrieve the user groups related to a list

HTTP request

GET

https://sarbacaneapis.com/v1/lists/{listId}/teams

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Errors

HTML Code	Error message	Description
400	NEED_ACCOUNT_ID	No account ID specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/lists/{listId}/teams"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/lists/{listId}/teams"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "teams": [
      "9cee994b1836fe00018126b1",
      "9cee994b1836fe00018126b2"
    ]
}

Edit groups related to a list

Allows you to edit groups of users reated to a list.

HTTP request

PUT

https://sarbacaneapis.com/v1/lists/{listId}/teams

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
teams	Table containing group ids to be related to the list	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/lists/{listId}/fields/{fieldId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{ "kind": "STRING", "caption": "New name"}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/lists/{listId}/fields/{fieldId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{ "kind": "STRING", "caption": "New name"}'

HTTP success response code

HTTP/2 200

Response body

{
    "caption": "New name",
    "id": "RIUxng6TSyy1VRSWChPMnA",
    "kind": "STRING"
}

List custom fields

Allows you to retrieve custom fields (columns) from a list.

HTTP request

GET

https://sarbacaneapis.com/v1/lists/{listId}/fields

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
listId	List ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
498	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/lists/{listId}/fields"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/lists/{listId}/fields"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "fields": [
        {
            "caption": "Creation Date",
            "id": "CREATION_DATE_ID",
            "kind": ""
        },
        {
            "caption": "Modification Date",
            "id": "MODIFICATION_DATE_ID",
            "kind": ""
        },
        {
            "caption": "email",
            "id": "EMAIL_ID",
            "kind": ""
        },
        {
            "caption": "phone",
            "id": "PHONE_ID",
            "kind": ""
        },
        {
            "caption": "Nom",
            "id": "AIUxng6TSyy1VRSWChPMnA",
            "kind": "STRING"
        },
        {
            "caption": "Inscrit",
            "id": "Be3o05ylR1Obz83GZc1Dkw",
            "kind": "BOOL"
        },
        {
            "caption": "Age",
            "id": "CyWAmoViRGyj_vtxMgg-qA",
            "kind": "INT"
        },
        {
            "caption": "Anniversaire",
            "id": "DbwHHDIiSEWER5KUyrIJVQ",
            "kind": "DATE"
        },
        {
            "caption": "ADDRESS",
            "id": "Ei_23RzYRF2MOzz_h__eLA",
            "kind": "STRING"
        }
    ]
}

Add a field

Adds a field (column) to a list.

HTTP request

POST

https://sarbacaneapis.com/v1/lists/{listId}/fields

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
kind	STRING, BOOL, INT or DATE	yes
caption	Column name	yes

URL parameters

Parameter	Description	Required
listid	List ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
403	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/fields"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{ "kind": "STRING", "caption": "ADDRESS" }'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/fields"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{ "kind": "STRING", "caption": "ADDRESS" }'

HTTP success response code

HTTP/2 200

Response body

{
    "caption": "ADDRESS",
    "id": "Ei_23RzYRF2MOzz_h__eLA",
    "kind": "STRING"
}

Edit a field

Allows you to edit a field.

HTTP request

PUT

https://sarbacaneapis.com/v1/lists/{listId}/fields/{fieldId}

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
kind	STRING, BOOL, INT or DATE	yes
caption	Column name	yes

URL parameters

Parameter	Description	Required
listId	List ID	yes
fieldId	Custom field ID	yes

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/lists/{listId}/fields/{fieldId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{ "kind": "STRING", "caption": "New name"}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/lists/{listId}/fields/{fieldId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{ "kind": "STRING", "caption": "New name"}'

HTTP success response code

HTTP/2 200

Response body

{
    "caption": "New name",
    "id": "RIUxng6TSyy1VRSWChPMnA",
    "kind": "STRING"
}

Delete all fields

Allows you to delete all the fields (columns) in a list.

HTTP request

DELETE

https://sarbacaneapis.com/v1/lists/{listId}/fields

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
listId	List ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X  DELETE "https://sarbacaneapis.com/v1/lists/{listId}/fields"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X DELETE "https://sarbacaneapis.com/v1/lists/{listId}/fields"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

List contacts

Allows you to list contacts included in a list.

HTTP request

GET

https://sarbacaneapis.com/v1/lists/{listId}/contacts

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
listId	List ID	yes
offset	Starting position	no
limit	Maximum number of elements returned - Max: 1,000	no
email	Email address	no
phone	Phone number	no
start	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no
end	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no
search	Search for text in contact fields	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/lists/{listId}/contacts?offset=0&limit=2&search=gmail"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/lists/{listId}/contacts?offset=0&limit=2&search=gmail"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body


[
    {
        "created": "2018-05-25T09:12:29Z",
        "edited": "2018-05-25T09:12:29Z",
        "email": "user1@sarbacane.com",
        "ialonrh54rrpmjvj1ywn": "3 rue des lilas 59000 LILLE",
        "id": "jfjC1uwfRKCLWOkAYkzSrA",
        "phone": "+33600000001"
    },
    {
        "created": "2018-05-25T09:09:50Z",
        "edited": "2018-05-25T09:09:50Z",
        "email": "user2@sarbacane.com",
        "ialonrh54rrpmjvj1ywn": "51 rue de la gare 92000 PARIS",
        "id": "CYeg4jdgSKqXwmGaXQwjrA",
        "phone": "+33600000002"
    }
]

Add a contact

Allows you to add a contact to a list.

HTTP request

POST

https://sarbacaneapis.com/v1/lists/{listId}/contacts

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
listId	List ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/contacts"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{   "email": "user3@sarbacane.com",
        "phone": "+33600000003",
        "nvVhK7dwSJyPAbFKrfUtjw": "18 rue de la plage 33000 BORDEAUX" }'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/contacts"
-H "accountId: YOUR_ACCOUNTID"
-H "apiKey: YOUR_API_KEY"
-d '{   "email": "user3@sarbacane.com",
    "phone": "+33600000003",
    "nvVhK7dwSJyPAbFKrfUtjw": "18 rue de la plage 33000 BORDEAUX" }'

HTTP success response code

HTTP/2 200

Response body

[
    "Mru3FE5fQnepxDgvuz3M9A",
    "2018-05-25T09:50:15Z",
    "2018-05-25T09:50:15Z",
    "user3@sarbacane.com",
    "+33600000003",
    "18 rue de la plage 33000 BORDEAUX"
]

Edit a contact

Allows you to edit a contact in a listv

HTTP request

PUT

https://sarbacaneapis.com/v1/lists/{listId}/contacts/{contactId}

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
listId	List ID	yes
contactId	Contact ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/lists/{listId}/contacts/{contactId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"email": "newEmail@sarbacane.com", "phone": "+33670000001", "ialonrh54rrpmjvj1ywn": "Nouvelle adresse"}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/lists/{listId}/contacts/{contactId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"email": "newEmail@sarbacane.com", "phone": "+33670000001", "ialonrh54rrpmjvj1ywn": "Nouvelle adresse"}'

HTTP success response code

HTTP/2 200

Response body

Add/Edit a contact

Allows you to add or update a contact in a list. If the contact does not exist, it will be added. If it does exist, it will be updated. Is considered as a contact a unique email / phone pair.

HTTP request

POST

https://sarbacaneapis.com/v1/lists/{listId}/contacts/upsert

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	email address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
listId	List ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/contacts/upsert"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{   "email": "user3@sarbacane.com",
        "phone": "+33600000003",
        "nvVhK7dwSJyPAbFKrfUtjw": "18 rue de la plage 33000 BORDEAUX" }'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/contacts/upsert"
-H "accountId: YOUR_ACCOUNTID"
-H "apiKey: YOUR_API_KEY"
-d '{   "email": "user3@sarbacane.com",
    "phone": "+33600000003",
    "nvVhK7dwSJyPAbFKrfUtjw": "18 rue de la plage 33000 BORDEAUX" }'

HTTP success response code

HTTP/2 200

Response body

[
    "Mru3FE5fQnepxDgvuz3M9A",
    "2018-05-25T09:50:15Z",
    "2018-05-25T09:50:15Z",
    "user3@sarbacane.com",
    "+33600000003",
    "18 rue de la plage 33000 BORDEAUX"
]

Add a block of contacts (JSON)

Allows you to add a block (JSON) of contacts (Max: 4MB per request / 1000 contacts per request). You can add a parameter to the URL to switch to UPSERT (?upsert=true). In this way, new contacts will be created and existing contacts will be updated. A contact is considered to be a unique email / phone pair.

HTTP request

POST

https://sarbacaneapis.com/v1/lists/{listId}/contacts/import

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
upsert	Upsert option: ?upsert=true	no
email	Email address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
listId	List ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication


curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/contacts/import"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '[{"email": "user1@domain.com", "phone": "+33600000001", "nvVhK7dwSJyPAbFKrfUtjw": "18 rue de la plage 33000 BORDEAUX" }, \
        {"email": "user2@domain.com", "phone": "+33600000002", "nvVhK7dwSJyPAbFKrfUtjw": "05 rue de Tourcoing 59000 LILLE" }, \
        {"email": "user3@domain.com", "phone": "+33600000003", "nvVhK7dwSJyPAbFKrfUtjw": "115 boulevard émile Zola 69000 LYON" } ]'

HTTP header authentication


curl -X POST "https://sarbacaneapis.com/v1/lists/{listId}/contacts/import"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '[{"email": "user1@domain.com", "phone": "+33600000001", "nvVhK7dwSJyPAbFKrfUtjw": "18 rue de la plage 33000 BORDEAUX" }, \
    {"email": "user2@domain.com", "phone": "+33600000002", "nvVhK7dwSJyPAbFKrfUtjw": "05 rue de Tourcoing 59000 LILLE" }, \
    {"email": "user3@domain.com", "phone": "+33600000003", "nvVhK7dwSJyPAbFKrfUtjw": "115 boulevard émile Zola 69000 LYON" } ]'

HTTP success response code

HTTP/2 200

Response body

{
    "invalid": 0,
    "valid": 3
}

Delete a contact

Removes a contact from a list.

HTTP request

DELETE

https://sarbacaneapis.com/v1/lists/{listId}/contacts?email={contactEmail}

Header parameters

Parameter	Description	Required
accountId	Accoun ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
listId	List ID	yes
contactId	Contact ID	no
email	Email address	no
phone	Phone number	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X DELETE "https://sarbacaneapis.com/v1/lists/{listId}/contacts?email=user1@domain.com"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication


curl -X DELETE "https://sarbacaneapis.com/v1/lists/{listId}/contacts?email=user1@domain.com"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
}

List blacklists

Retrieves all available blacklists.

HTTP request

GET

https://sarbacaneapis.com/v1/blacklists

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
offset	Starting position	no
limit	Maximum number of elements returned - Max: 1,000	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

Add a blacklist

Allows you to add a blacklist.

HTTP request

POST

https://sarbacaneapis.com/v1/blacklists

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
name	Blacklist name	yes
teams	Table containing group ids to be related to the blacklist	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"name": "Nom de la liste"}'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"name": "Nom de la liste"}'

HTTP success response code

HTTP/2 200

Response body

{
    "blacklist": {
        "created": "2017-09-14T12:51:14Z",
        "creator": "API",
        "id": "rqWxwoUMRqKJDkyfUG8UAA",
        "kind": "BLACKLIST",
        "modified": "2017-09-14T12:51:14Z",
        "modifier": "API",
        "name": "Exemple"
    }
}

Edit a blacklist

Allows you to edit a blacklist.

HTTP request

PUT

https://sarbacaneapis.com/v1/blacklists/{blacklistId}

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
name	Blacklist name	no
readOnly	Set list to read-only	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"name": "Nouveau nom de la liste", "readOnly": false}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{bkacklistId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"name": "Nouveau nom de la liste", "readOnly": false}'

HTTP success response code

HTTP/2 200

Response body

{
    "created": "2017-09-14T12:51:14Z",
    "id": "rqWxwoUMRqKJDkyfUG8UAA",
    "kind": "BLACKLIST",
    "modified": "2017-09-14T18:24:12Z",
    "name": "Nouveau nom de la liste",
    "readOnly": "false"
}

Delete a blacklist

Allows you to delete a blacklist

HTTP request

DELETE

https://sarbacaneapis.com/v1/blacklists/{blacklistId}

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUND_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X DELETE "https://sarbacaneapis.com/v1/blacklists/{blacklistId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X DELETE "https://sarbacaneapis.com/v1/blacklists/{blacklistId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{ }

List groups related to a blacklist

Retrieves user groups related to a blacklist.

HTTP request

GET

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/teams

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	SERVICE_*_UNREACHABLE	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/teams"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/teams"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "teams": [
      "9cee994b1836fe00018126b1",
      "9cee994b1836fe00018126b2"
    ]
}

Edit groups related to a blacklist

Allows you to edit the user groups related to a blacklist.

HTTP request

PUT

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/teams

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
teams	Table containing group ids to be related to the blacklist	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/teams"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"teams": ["9cee994b1836fe00018126b1", "9cee994b1836fe00018126b2"]}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/teams"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"teams": ["9cee994b1836fe00018126b1", "9cee994b1836fe00018126b2"]}'

HTTP success response code

HTTP/2 200

Response body

List custom fields from blacklists

Retrieves custom fields (columns) from a blacklist.

HTTP request

GET

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/fields

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/fields"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/fields"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "fields": [
        {
            "caption": "EMAIL",
            "id": "EMAIL_ID",
            "kind": ""
        },
        {
            "caption": "PHONE",
            "id": "PHONE_ID",
            "kind": ""
        }
    ]
}

List bounces

Lists invalid contacts from a blacklist.

HTTP request

GET

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes
offset	Starting position	no
limit	Maximum number of elements returned - Max: 1,000	no
email	Email address	no
phone	Phone number	no
start	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no
end	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces?offset=0&limit=2"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces?offset=0&limit=2"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "contacts": [
        {
            "contact": [
                "2017-09-18T08:11:57Z",
                "2017-09-18T08:11:57Z",
                "user@domain.com",
                "+33600000001"
            ]
        },
        {
            "contact": [
                "2017-09-15T12:35:00Z",
                "2017-09-15T12:36:13Z",
                "user1@domain.com",
                "+33600000001"
            ]
        }
    ]
}

Add a bounce

Adds an invalid contact to a blacklist.

HTTP request

POST

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000000"}'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000000"}'

HTTP success response code

HTTP/2 200

Response body

{
    "id": "LH8XG_jpRS2J6fLW_U11WA"
}

Add a block of bounces

Adds a block of invalid contacts (JSON) to a blacklist (Max: 4MB per request).

HTTP request

POST

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces/import

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces/import"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '[ {"email": "user@domain.com", "phone": "+33600000001" }, {"email": "user2@domain.com", "phone": "+33600000002"} ]'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces/import"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '[ {"email": "user@domain.com", "phone": "+33600000001" }, {"email": "user2@domain.com", "phone": "+33600000002"} ]'

HTTP success response code

HTTP/2 200

Response body

{
    "invalid": 0,
    "valid": 2
}

Edit bounce

Allows you to edit an invalid contact in a blacklist.

HTTP request

PUT

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
newEmail	New email address	no
newPhone	New phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000000", "newEmail": "user_modified@domain.com"}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000000", "newEmail": "user_modified@domain.com"}'

HTTP success response code

HTTP/2 200

Response body

{
    "contact": [
        "2017-09-18T08:17:17Z",
        "2017-09-15T12:35:00Z",
        "user_modified@domain.com",
        "+33600000001"
    ]
}

Delete bounce

Removes an invalid contact from a blacklist.

HTTP request

DELETE

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/bounces

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes
email	Email address	no
phone	Phone number	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

List unsubscribed contacts

Lists unsubscribed contacts from a blacklist

HTTP request

GET

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes
offset	Starting position	noo
limit	Maximum number of elements returned - Max: 1,000	no
email	Email address	no
phone	Phone number	no
start	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no
end	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers?offset=0&limit=2"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers?offset=0&limit=2"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "contacts": [
        {
            "contact": [
                "2017-09-18T08:11:57Z",
                "2017-09-18T08:11:57Z",
                "user@domain.com",
                "+33600000001"
            ]
        },
        {
            "contact": [
                "2017-09-15T12:35:00Z",
                "2017-09-15T12:36:13Z",
                "user1@domain.com",
                "+33600000001"
            ]
        }
    ]
}

Add an unsubscribed contact

Allows you to add an unsubscribed contact to a blacklist.

HTTP request

POST

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
fieldId	Custom field ID	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000000"}'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000000"}'

HTTP success response code

HTTP/2 200

Response body

{
    "id": "LH8XG_jpRS2J6fLW_U11WA"
}

Add a block of unsubscribed contacts

Add a block of unsubscribed contacts

Allows you to add a block of unsubscribers (JSON) to a blacklist (Max: 4MB per request).

HTTP request

POST

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers/import

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers/import"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '[ {"email": "user@domain.com", "phone": "+33600000001" }, {"email": "user2@domain.com", "phone": "+33600000002"} ]'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers/import"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '[ {"email": "user@domain.com", "phone": "+33600000001" }, {"email": "user2@domain.com", "phone": "+33600000002"} ]'

HTTP success response code

HTTP/2 200

Response body

{
    "invalid": 0,
    "valid": 2
}

Edit unsubscribed contact

Allows you to edit an unsubscribed contact in a blacklist.

HTTP request

PUT

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
newEmail	New email address	no
newPhone	New phone number	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000001", "newEmail": "user_modified@domain.com"}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000001", "newEmail": "user_modified@domain.com"}'

HTTP success response code

HTTP/2 200

Response body

{
    "contact": [
        "2017-09-18T08:17:17Z",
        "2017-09-15T12:35:00Z",
        "user_modified@domain.com",
        "+33600000001"
    ]
}

Delete an unsubscribed contact

Allows you to remove an unsubscribed contact from a blacklist.

HTTP request

DELETE

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes
email	Email address	no
phone	Phone number	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X DELETE "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers?email=user@domain.com&phone=%2B33647474452"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X DELETE "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/unsubscribers?email=user@domain.com&phone=%2B33647474452"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response bodyResponse body

{
}

List complainants

HTTP request

GET

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes
offset	Starting position	no
limit	Maximum number of elements returned - Max: 1,000	no
email	Email address	no
phone	Phone number	no
start	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no
end	Filter by modification date (ISO date: 2019-04-25T08:31:43.280Z)	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints?limit=10&offset=2"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X GET "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints?limit=10&offset=2"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "contacts": [
        {
            "contact": [
                "2017-09-18T08:11:57Z",
                "2017-09-18T08:11:57Z",
                "user@domain.com",
                "+33600000001"
            ]
        },
        {
            "contact": [
                "2017-09-15T12:35:00Z",
                "2017-09-15T12:36:13Z",
                "user1@domain.com",
                "+33600000001"
            ]
        }
    ]
}

Add a complainant

Add a complainant to a blacklist.

HTTP request

POST

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d -d '{"email": "user@domain.com", "phone": "+33600000000"}'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000000"}'

HTTP success response code

HTTP/2 200

Response body

{
    "id": "LH8XG_jpRS2J6fLW_U11WA"
}

Add a block of complainants

Add a block of complainants (JSON) to a blacklist (Max: 4MB per request).

HTTP request

POST

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints/import

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API Key	yes

Body Parameters

Parameter	Description	Required
email	Email Address	no
phone	Phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	FAILED TO ACQUIRE LOCK	Target in use by another resource
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints/import"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '[ {"email": "user@domain.com", "phone": "+33600000001" }, {"email": "user2@domain.com", "phone": "+33600000002"} ]'

HTTP header authentication

curl -X POST "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints/import"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '[ {"email": "user@domain.com", "phone": "+33600000001" }, {"email": "user2@domain.com", "phone": "+33600000002"} ]'

HTTP success response code

HTTP/2 200

Response body

{
    "invalid": 0,
    "valid": 2
}

Edit a complainant

Allows you to edit a blacklisted complainant.

HTTP request

PUT

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
email	Email address	no
phonne	Phone number	no
newEmail	New email address	no
newPhone	New phone number	no
fieldId	Custom field ID	no

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID specified in request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000001", "newEmail": "user_modified@domain.com"}'

HTTP header authentication

curl -X PUT "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"email": "user@domain.com", "phone": "+33600000001", "newEmail": "user_modified@domain.com"}'

HTTP success response code

HTTP/2 200

Response body

{
    "contact": [
        "2017-09-18T08:17:17Z",
        "2017-09-15T12:35:00Z",
        "user_modified@domain.com",
        "+33600000001"
    ]
}

Delete a complainant

Removes a complainant from a blacklist.

HTTP request

DELETE

https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints

Header parameters

Parameter	Description	Required
accountId	Account ID	yes
apiKey	API Key	yes

URL parameters

Parameter	Description	Required
blacklistId	Blacklist ID	yes
email	Email address	no
phone	Phone number	no

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal service error, please contact support

HTTP authentication

curl -X DELETE "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints?email=user@domain.com&phone=%2B33647474452"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP header authentication

curl -X DELETE "https://sarbacaneapis.com/v1/blacklists/{blacklistId}/complaints?email=user@domain.com&phone=%2B33647474452"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
}