Getting started

Tutorial outline

Once you’ve completed this tutorial, you’ll have:

  • Authenticated with the API
  • Created your first contact attribute and reviewed it
  • Created your first contact and reviewed it
  • Made a search for a contact based on an attribute using the query syntax

First, you will need…

  • A Cakemail account with its associated email and password. If you don’t have an account yet, create one here.
  • A Cakemail Client ID and Client Secret. These are provided to you when you register your app.

Authenticate and retrieve your access token

More information: Authenticating with OAuth

Request

curl -X POST \
https://login.cakemail.com/auth/realms/cakemail_integration/protocol/openid-connect/token \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'username={email}&password={password}&client_id={client_id}&client_secret={client_secret}&
grant_type=password'

Response

{
	"access_token": "eyJhbGciOiJSUzI1NiIsIn...wnBCbColgw",
	"expires_in": 300,
	"refresh_expires_in": 1800,
	"refresh_token": "eyJhbGciOiJSUzI1NiIdi...CfP8lLF22z",
	"token_type": "bearer",
	"id_token": "eyJhbGciOiJSUzI1NiI...Tm7fEo7yOWQ",
	"not-before-policy": 0,
	"session_state": "db957649-4efe-49db-9c9f-e244c9c05e4c"
}

The access_token will be used to make authenticated calls to the API

 

Contacts API

Create a contact attribute

.

Create the ‘name’ attribute

Request

curl -X POST \
https://v1.cakemailapi.com/contact/attributes \
-H 'authorization: Bearer [access_token]' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json'
-d '{
	"name": "name",
	"type": "string"
}'

Response

{
	"id": "0c4334b9-5s8b-4161-9e12-23db68f5b8f6",
	"name": "name",
	"type": "string",
	"lastName": "Name"
}

Review contact attributes

More information: Get all attributes reference

.

Request

curl -X GET \
https://v1.cakemailapi.com/contact/attributes \
-H 'authorization: Bearer [access_token]' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json'

Response

{
   "count":1,
   "Items":[
      {
         "id":"0c4334b9-5s8b-4161-9e12-23db68f5b8f6",
         "name":"name",
         "section":null,
         "type":"string",
         "tags":[

         ]
      }
   ]
}

Create a contact

Create yourself as your first contact

More information: Create a new contact reference

.

Request

curl -X POST \
https://v1.cakemailapi.com/contacts \
-H 'authorization: Bearer [access_token]' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json'
-d '{
   "email":"example@domain.com",
   "personal":"Example",
   "consent":"express",
   "status":"active",
   "locale":"fr",
   "attributes":{
      "name":"Example"
   }
}'

Response

{
	"email": "example@domain.com",
	"personal": "Example",
	"consent": "express",
	"consentDate": "2017-10-24T15:35:13.072Z",
	"status": "active",
	"source": null,
	"referrer": null,
	"locale": "fr",
	"timeZone": null,
	"interests": {
		"subscribed": [],
		"unsubscribed": []
	},
	"attributes": {
		"name": "Example"
	},
	"id": "ed38...0ad6e",
	"created": "2017-10-24T15:35:13.072Z",
	"updated": null,
	"consentExpiration": null
}

 

Review contacts

More information: Get all contacts reference

.

Request

curl -X GET \
https://v1.cakemailapi.com/contacts \
-H 'authorization: Bearer [access_token]' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json'

Response

{
   "count":1,
   "items":[
      {
         "email":"example@domain.com",
         "personal":"Example",
         "consent":"express",
         "consentDate":"2017-10-24T15:35:13.072Z",
         "status":"active",
         "source":null,
         "referrer":null,
         "locale":"fr",
         "timeZone":null,
         "interests":{
            "subscribed":[

            ],
            "unsubscribed":[

            ]
         },
         "attributes":{
            "name":"Example"
         },
         "id":"ed38...ad6e",
         "created":"2017-10-24T15:35:13.072Z",
         "updated":null,
         "consentExpiration":null
      }
   ]
}

Search for a contact

Contacts can be searched by attributes as well as items found as per their definition in the documentation.

.

More information: Contact segment query syntax

.

Request

curl -X POST \
https://v1.cakemailapi.com/contact/search \
-H 'authorization: Bearer [access_token]' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json'
-d '{"attributes[name]":"Example"}'

 

Response

{
   "count":1,
   "items":[
      {
         "email":"example@domain.com",
         "personal":"Example",
         "consent":"express",
         "consentDate":"2017-10-24T15:35:13.072Z",
         "status":"active",
         "source":null,
         "referrer":null,
         "locale":"fr",
         "timeZone":null,
         "interests":{
            "subscribed":[

            ],
            "unsubscribed":[

            ]
         },
         "attributes":{
            "name":"Example"
         },
         "id":"ed38...ad6e",
         "created":"2017-10-24T15:35:13.072Z",
         "updated":null,
         "consentExpiration":null
      }
   ]
}
Updated on November 8, 2017

Was this article helpful?