Xink API Reference

Version: 1.4

Date: Jan 23, 2025

Table of Contents

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.

Authorization server URI: https://auth.xink.io
Token endpoint: /OAuth/Token

To get an access token, you need to make a POST request to the Token Endpoint:

 POST  https://auth.xink.io/OAuth/Token

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.

 GET  https://auth.xink.io/Discovery

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:

 GET  e-eu.xink.io/{api/1.0/...}

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

 GET  api/1.0/account/info
Scope: employeeread

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

 GET  api/1.0/employee/list/{offset:int=0}/{limit:int=500}
Scope: employeeread

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:

 GET  api/1.0/employee/list/0/3

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"
        },
        ...
    ]
}
    


 GET  api/1.0/employee/{email}/field
Scope: employeefieldsread

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
            },
            ...
        ]
    }


 GET  api/1.0/employee/{email}/signatures
Scope: employeesignaturesread

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


 POST  api/1.0/employee/upload
Scope: employeectrl

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


 POST  api/1.0/employee/delete
Scope: employeectrl

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.

 POST  api/1.0/image

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


 GET  api/1.0/image/list/{offset:int=0}/{limit:int=500}

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

 GET  api/1.0/signature/list/{offset:int=0}/{limit:int=500}
Scope: signaturectrl

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
        },

}


 POST  api/1.0/signature/
Scope: signaturectrl

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


 POST  api/1.0/signature/{id}/update
Scope: signaturectrl

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


 DELETE  api/1.0/signature/{id}
Scope: signaturectrl


 POST  api/1.0/signature/{id}/delete
Scope: signaturectrl


Signature Import

 POST  api/1.0/signatureimport/{id}/image
Scope: signaturectrl


 POST  api/1.0/signatureimport/{id}
Scope: signaturectrl


Rerouting

 POST  api/1.0/rerouting/status
Scope: None

Response example:


{
    "StatusCode": 0,
    "Domains": [],
    "IsSMTPCacheReady": true
}


 POST  api/1.0/rerouting/clearmap
Scope: None


 POST  api/1.0/rerouting/replacemap
Scope: None


Managed Accounts

 GET  api/1.0/managedAccounts/list
Scope: managedaccountsread

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

 POST  api/1.0/employees/{email}/sharesSignatureWith/{emailSharedWith}
Scope: employeectrl

Adds shared employee. The employee {emailSharedWith} can use the signatures of the employee {email}


 DELETE  api/1.0/employees/{email}/sharesSignatureWith/{emailSharedWith}
Scope: employeectrl

Deletes shared employee.


 GET  api/1.0/employees/{email}/shared
Scope: employeectrl

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

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.
Quick 1-on-1 Demo | Ⓒ 2025 Xink