Version: 1.4
Date: Jan 23, 2025
Table of Contents
- Overview
- Step 1. Authentication/Authorization
- Step 2. Discovery
- Step 3. Request to an APIRoot
- Summary of All Available API Controllers
- Examples of API Controller's Request-Response
Overview
Xink provides REST API for external clients. All traffic between a client application and Xink service is transported by encrypted HTTP requests and responses.
Step 1. Authentication/Authorization
We use OAuth2 to control access to Xink APIs, external clients should use ClientCredentialsGrant in particular. Client should request access token from Xink authorization server, then use the token in all subsequent requests to the API.
In Xink admin portal you need to create an API user. Navigate to Preferences -> Admins and add an API user. Give the user proper permissions and a good password. The user referred to in this documentation is an API user.
To get an access token, you need to make a POST request to the Token Endpoint:
With the following parameters:
{
"grant_type": "client_credentials",
"client_id": "your_client_id",
"client_secret": "your_client_secret"
"scope: "employeeread other_necessary_scopes"
}
Step 2. Discovery
We offer five data centers. First you should discover data center (APIRoot) belonging to your account. You make a GET request to get necessary details for your endpoint.
Example of a result for EU data center:
{
"Success": true,
"DataCenterID": "EU",
"APIRoot": "https://e-eu.xink.io",
"SyncRoot": "https://s-eu.xink.io",
"ImgRoot": "https://i-eu.xink.io",
"TrackingRoot": "https://t-eu.xink.io"
}
Step 3. Request to an APIRoot for the method
Use URL (APIRoot) you received from discovery step to make an API call for your method. Below we continue an example for EU:
Please note scope names employeeread and employeesignaturesread are required to get employee list and signatures. Each operation may require some scope.
By default token is valid for 2 hours since authorization request. On later stages, this value might be changed to 10-15 minutes.
Summary of All Available API Controllers
Account
Employee
Image
Signature
Signature Import
Rerouting
Managed Accounts
Shared Mailboxes
Examples of API Controller's Request-Response
Scopes
Scopes are used to control access to specific API endpoints. Below is a list of scopes and their corresponding API endpoints:
employeeread(READ)employeefieldsread(READ)employeectrl(WRITE)employeesignaturesread(READ)signaturectrl(WRITE)managedaccountsread(READ)
Account
Request parameters are not required.
Example response:
Response contains information about the account, including company name, licensed edition, count, created date, renewal date, invoice email, total employees, signatures, default signature, reply signature, running campaigns, upcoming campaigns, top campaigns, disabled campaigns and date from.
{
"CompanyName": "Some Company",
"LicensedEdition": "Xink Campaign",
"LicensedCount": 6,
"CreatedDate": "2013-02-07T07:37:52.78",
"RenewalDate": null,
"InvoiceEmail": "some@some.com",
"TotalEmployees": 530,
"Signatures": 32,
"DefaultSignature": null,
"ReplySignature": null,
"RunningCampaigns": [
{
"Name": "disclaimer2",
"ContentText": null,
"ContentHTML": "disclaimer2",
"Active": true,
"TrackClicks": true,
"Weight": 2,
"Notes": null,
"EffectiveActive": true,
"SignaturesCount": 0,
"ClickCount": 0,
"ViewCount": 8
},
...
{
"Name": "Subscribe",
"ContentText": null,
"ContentHTML": "",
"Active": true,
"TrackClicks": true,
"Weight": 1,
"Notes": null,
"EffectiveActive": true,
"SignaturesCount": 1,
"ClickCount": 11,
"ViewCount": 15
}
],
"UpcomingCampaigns": [],
"TopCampaigns": [],
"DisabledCampaigns": [
{
"Name": "__custom_tracking_link_01",
"ContentText": null,
"ContentHTML": null,
"Active": false,
"TrackClicks": true,
"Weight": 1,
"Notes": null,
"EffectiveActive": false,
"SignaturesCount": 1,
"ClickCount": 0,
"ViewCount": 53
},
...
{
"Name": "new campaign",
"ContentText": null,
"ContentHTML": null,
"Active": false,
"TrackClicks": true,
"Weight": 1,
"Notes": null,
"EffectiveActive": false,
"SignaturesCount": 0,
"ClickCount": 0,
"ViewCount": 0
}
],
"DateFrom": "2023-07-09T00:00:00+00:00"
}
Employee
Request parameters offset and limit are optional. If not provided, defaults are used: offset=0 and limit=500.
Example request to get first 3 employees starting from offset 0:
Response contains Offset and Limit parameters values used in the request (or defaults if no parameters were supplied); and actual array of Items, each represents one employee.
{
"Limit": 500,
"Offset": 0,
"SearchQuery": null,
"Items": [
{
"Email": "john@doe.com",
"FirstName": "John",
"LastName": "Doe",
"DisplayName": "Jonny D"
},
{
"Email": "maria@doe.com",
"FirstName": "Maria",
"LastName": "Doe",
"DisplayName": "Maria D"
},
...
]
}
Example respone to get fields for employee with email:
{
"Fields": [
{
"Code": "Country",
"DisplayName": "Country",
"FieldValue": null,
"IsImage": false
},
{
"Code": "DisplayName",
"DisplayName": "Display Name",
"FieldValue": "somename",
"IsImage": false
},
...
{
"Code": "LastName",
"DisplayName": "Last Name",
"FieldValue": "somename",
"IsImage": false
},
{
"Code": "Email",
"DisplayName": "Employee's Email",
"FieldValue": "test@some.com",
"IsImage": false
},
...
]
}
{
"Clean": false,
"SetDefault": true,
"SetReply": false,
"Signatures": [
{
"Name": "",
"HTML": null,
"Text": null,
"DefaultNew": false,
"DefaultReply": true
},
{
"Name": "(KM) 3-4-Sterne Offerte",
"HTML": ""
"Text": null,
"DefaultNew": false,
"DefaultReply": false
}
]
}
Clean flag represents value of "Delete all existing email signatures in Outlook" preference.
Signature supposed to be downloaded directly into Signatures folder of Outlook user profile. Each signature must be saved into a file named exactly as field Name value with .html extension added.
Example request:
{
"Items": [
{
"Email":"user1@testapi.com",
"FirstName":"John",
"LastName":"Doe",
"DisplayName":"John Doe",
"Fields": [
{
"Code":"City",
"FieldValue":"New York"
},
{
"Code":"Country",
"FieldValue":"USA"
}
]
},
{
"Email":"user2@testapi.com",
"FirstName":"Peter",
"LastName":"Johnson",
"DisplayName":"",
"Fields": [
{
"Code":"Department",
"FieldValue":"Sales"
},
{
"Code":"Facebook",
"FieldValue":""
}
]
}
]
}
Response:
{
"Items": [
"user1@testapi.com: OK",
"user2@testapi.com: OK"
]
}
Example request:
{
"Items": [
{
"Email":"user1@testapi.com"
},
{
"Email":"user2@testapi.com"
}
]
}
Response: None
Image
Signature may contain images, like company logo, employee avatar or whatever else. Xink stores those images and performs several actions to prepare Outlook application to use them properly.
Field Name provides exact file name for corresponding image. Images supposed to be saved in the same directory as signatures. It is important; signature HTML refers images just by file name.
Xink server is responsible for making image names unique. If in any case image names are repeated, it is guaranteed that these are references to the same image.
There is no dedicated authorization scope for image access. It is enough to provide a token generated for valid client account.
Set parameters for Image:
{
"Content-Type": "multipart/form-data",
"Key": "file",
"Value": "someImg.png"
}
Example response:
{
"AccountUniqueName": "BT4",
"ImageUniqueName": "i",
"RelativeImageUrl": "https://i.xink.io/Images/Get/BT4/i.png",
"Name": "img21.png",
"DateCreated": "2023-10-10T09:18:18.21",
"MD5": "3A16278045564DAEIUB5A52B23C8B",
"SHA1": "A327FCE8098NIJN1E39D2683616DE71CBA4"
}
Request parameters offset and limit are optional. If not provided, defaults are used: offset=0 and limit=500:
{
"Limit": 500,
"Offset": 0,
"Items": [
{
"AccountUniqueName": "B4",
"ImageUniqueName": "i6",
"RelativeImageUrl": "https://i.xink.io/Images/Get/B4/i6.png",
"Name": "image001.png",
"DateCreated": "2014-06-18T11:59:38.843",
"MD5": "255F0174C3EOKN230283222FEE",
"SHA1": "89E5C303A9D90283NEED815735FF2C5239871"
},
{
"AccountUniqueName": "B3",
"ImageUniqueName": "i1",
"RelativeImageUrl": "https://i.xink.io/Images/Get/B3/i1.png",
"Name": "image002.png",
"DateCreated": "2014-06-18T12:19:18.76",
"MD5": "51BCBB0923NJEB223A2BA122E0",
"SHA1": "FC4907WOEINR0293712AF8BF8D9C727D15"
}
]
}Signature
Request parameters offset and limit are optional. If not provided, defaults are used: offset=0 and limit=500. Example Response:
{
"Limit": 500,
"Offset": 0,
"Items": [
{
"SignatureID": "372236",
"Name": "eMailSignature",
"ContentText": "((FirstName)) ((LastName))\r\n((JobTitle))\r\n\r\n((Company))\r\n((Department))\r\nEmail: ((Email))\r\nPhone: ((DirectPhone))\r\n((WebSite))",
"ContentHTML": "Content",
"DefaultNew": false,
"DefaultReply": false,
"Available": false,
"Public": false,
"Notes": null
},
}
Parameters:
- Name (string, required): The name of the signature
- ContentText (string, required): The text content of the signature
- ContentHTML (string, required): The HTML content of the signature
- Notes (string, optional): Optional notes about the signature
Example request:
{
"Name": "MySignature",
"ContentText": "Hello, this is my signature text.",
"ContentHTML": "Hello, this is my HTML signature.",
"Notes": "Optional notes about the signature"
}Response:
{
"SignatureID": "12345"
}Request:
{
"Name": "MySignature-UPDATED",
"ContentText": "Hello, this is my signature text UPDATED.",
"ContentHTML": "Hello, this is my HTML signature UPDATED.",
"Notes": "Optional notes about the signature UPDATED"
}
Response:
{
"SignatureID": "12345"
}Signature Import
Rerouting
Response example:
{
"StatusCode": 0,
"Domains": [],
"IsSMTPCacheReady": true
}
Managed Accounts
Response example:
{
"Items": [
{
"id": 26845,
"name": "admin1",
"email": "admin1@xink.io",
"employees": 1,
"licenses": 0,
"version": "Brand",
"using": 0,
"note": "4",
"folders": [],
"createdDate": "2019-02-22T08:45:29.36",
"endDate": null
},
{
"id": 28760,
"name": "admin2@xink.io",
"email": "admin2@xink.io",
"employees": 1,
"licenses": 0,
"version": "Brand",
"using": 0,
"note": "111221",
"folders": [
"1"
],
"createdDate": "2019-04-24T15:22:24.157",
"endDate": "2019-05-08T00:00:00"
},
{
"id": 30598,
"name": "admin3",
"email": "aadmin1@xink.io",
"employees": 1,
"licenses": 0,
"version": "Brand",
"using": 0,
"note": "2",
"folders": [
"1",
"2"
],
"createdDate": "2019-06-18T06:58:56.243",
"endDate": null
}
]
}
Shared Mailboxes
Adds shared employee. The employee {emailSharedWith} can use the signatures of the employee {email}
Deletes shared employee.
Returns a list of shared employees whose signatures can be used by employee {email}
Response example:
{
"Email": "joe@xink.io",
"SharedEmployees": [
{
"Email": "sam@xink.io",
"DisplayName": "Sam Doe"
}
]
}
