API Reference

Thanks for subscribing.

Overview

Freshmarketer's APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding or deleting data from your marketing system.

Which are the API commands used in Freshmarketer?

Command Purpose
POST Create an object
GET Fetch one or more objects
PUT Update an object
DELETE Remove an object

Authentication

To use the API’s listed above, you need to authenticate your id as you would when you log in to your Freshmarketer account using your API key.

  1. API key

    Each user in Freshmarketer is provided with a unique API key. To find your API key

    1. Click Settings from let nav panel
    2. Click the API Settings
    3. You can find your API key in the field Your API key.

    Learn more about finding your API key.

For example, if your API key is sfg999666t673t7t82, the curl command to use is:

curl -H fm-token=sfg999666t673t7t82" -XGET https://domain.freshmarketer.com/mas/api/v1/contacts

What are the resources available via the API?

Any information in your Freshmarketer’s account can be identified by its own unique identifier or "URI". If you want data from your marketing system, be it a contact or list of an account, you’d need its respective identifier to fetch the data via the API’s. All URIs follow the following format:

https://your_domain_name/mas/api/v1/resource_name

For example, if you’d like to fetch the contact with id 144 from your account "smarketing.freshmarketer.com", the syntax would be

https://smarketing.freshmarketer.com/mas/api/v1/contacts/144

Note:
We’ve shortened the API resource URLs throughout this document by omitting the domain name, meaning, /api/v1/contacts is actually a shorter version of https://domain.freshmarketer.com/api/v1/contacts

Will everyone have the same access rights?

No. Using the API’s, users would only be able to view data that they have access to. Learn more about managing user roles and scopes.

Schema

Blank Fields:
Blank fields are made null instead of being omitted.

Timestamps:
All timestamps are returned in the UTC format, YYYY-MM-DDTHH:MM:SSZ. For example, 2016-02-13T23:27:49Z

Date Fields:
Input for date fields is expected to be in one of the following formats:
YYYY-MM-DD
YYYY-MM-DDTHH:MM
YYYY-MM-DDTHH:MMZ
YYYY-MM-DDTHH:MM:SS
YYYY-MM-DDTHH:MM:SSZ
YYYY-MM-DDTHH:MM:SS±hh:mm
YYYY-MM-DDTHH:MM:SS±hh
YYYY-MM-DDTHH:MM:SS±hhmm
If the time zone information is not present, it will be assumed to be in UTC.
A few valid date fields - 2016-02-15T21:16:25Z ,    2012-12-24T12:56:15+05:30,    2010-03-23T12:00

Errors

I have encountered an error. How do I fix this?

API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error and fix it. You can use the table below to understand what each code means.

HTTP Status Code Text Description
400* Client or Validation Error Indicates that the request is not in the correct format. For example, the Create a contact API requires a valid email address to be sent as part of the request. If you are missing @ as part of the email address in the request, you would get this error code.
401 Authentication Failure Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here.
403 Access Denied This indicates that the user whose credentials were used in making this request was not authorized to perform this API call. It could be that this API call requires admin level credentials or perhaps the Freshmarketer portal doesn't have corresponding feature enabled.
404 Requested Resource not Found This status code is returned when the request contains invalid ID/Freshmarketer domain in the URL or an invalid URL itself. For example, an API call to retrieve a contact with an invalid ID will return a HTTP 404 status code to let you know that no such contact exists.
429 Too many requests This status code appears when the user has exceeded the API limit set per hour per account. In Fresmarketer, this limit is 1000 API requests per hour per account.
500 Unexpected Server Error Phew!! You can't do anything more here. This indicates an error at Freshmarketer's side. Please email us your API script along with the response headers. We will reach you out to you and fix this ASAP.

Error Response

In addition to the HTTP status code, most errors would also return a response body that contains more information on the error. Here’s a sample error response,

Sample Error 
1
2
3
4
5
6
7
{
    "errors": {
            "code":"Status code of the error",
            "message":"Error Description"
        }
}

Error Response Fields
Field Description
code HTTP error status code
message Description about the error.

Contacts

Contacts represent the companies (Accounts) that you do business with.

ATTRIBUTE TYPE DESCRIPTION
first_name string First name of the contact
middle_name string Middle name of the contact
last_name string Last name of the contact
email* string Primary email address of the contact
source string Where the contact from
subscriptions string Lists which contact subscribe to
company string Company of the contact
phone string Work phone number of the contact
mobile string Mobile phone number of the contact
facebook string Facebook account of the contact
twitter string Twitter account of the contact
linkedin string LinkedIn account of the contact
address string Address of the contact
city string City that the contact belongs to
state string State that the contact belongs to
zipcode string Zipcode of the region that the contact belongs to
country string Country that the contact belongs to
custom_field string List of custom fields
* Mandatory fields for creating contact.

Add/update a Contact

This API allows you to if a contact doesn't already exist, it will be created. If a contact with the same email address exists, it will be updated.

put
/mas/api/v1/contacts
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"first_name":"James", "last_name":"Sampleton (sample)", "email":"james.sampleton@sample.com", "status":"subscribed"}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
   "contact" : {
      "score" : null,
      "cf_dropdown_values" : {},
      "updated_at" : 1584699135294,
      "source_id" : 1,
      "custom_field" : {},
      "subscriptions" : null,
      "previous" : null,
      "org_id" : 1296005006,
      "state" : null,
      "last_name" : "Sampleton (sample)",
      "status" : "subscribed",
      "created_at" : 1584699135294,
      "email" : "james.sampleton@sample.com",
      "zipcode" : null,
      "company" : null,
      "subscription_type" : [
         41,
         42,
         43,
         44
      ],
      "city" : null,
      "fwMcrId" : null,
      "time_zone" : null,
      "first_name" : "James",
      "phone" : null,
      "middle_name" : null,
      "twitter" : null,
      "mobile" : null,
      "owner_id" : null,
      "contactable" : true,
      "uuid" : "4865f1a2-939d-472e-a544-6b6479da916e",
      "linkedin" : null,
      "facebook" : null,
      "id" : 1767723,
      "language" : null,
      "custom2" : [],
      "country" : null,
      "next" : null,
      "address" : null,
      "source" : "native_form"
   }
}
EXPAND ↓

Note

1. Add a contact with custom fields
If you’d like to add a contact along with custom fields, use this API.

Copied Copy 
1
curl -H "fm-token:sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"first_name":"James", "last_name":"Sampleton (sample)", "email": "james.sampleton@sample.com", "mobile_number":"1-926-555-9503", "status":"subscribed", "custom_field": {"cf_producttype": "saas","cf_purchasedate":"2020-03-19T18:30:00.000Z","cf_totalamount":780.56} }' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓

2. Update a Contact's email address
We can not update contact's email address via the regular "email" field. To update the email address have to provide the new email address in the field called "new_email" .

Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"status":"subscribed", "email":"james.sampleton@sample.com","new_email":"davidjames.sampleton@sample.com"}}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓

Subscribe/unsubscribe a Contact

This API allows you to if a contact doesn't already subscribe it will be updated.

PUT
/mas/api/v1/contacts
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"email":"james.sampleton@sample.com", "status":"subscribed"}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
   "contact" : {
      "created_at" : 1584699085000,
      "company" : null,
      "source_id" : 1,
      "language" : null,
      "subscription_type" : [
         97,
         41,
         42,
         43,
         44
      ],
      "owner_id" : null,
      "score" : null,
      "email" : "james.sampleton@sample.com",
      "last_name" : "Thompson (sample)",
      "twitter" : null,
      "cf_dropdown_values" : {},
      "updated_at" : 1584707737460,
      "id" : 1767722,
      "custom2" : [],
      "phone" : null,
      "fwMcrId" : null,
      "city" : null,
      "subscriptions" : null,
      "facebook" : null,
      "uuid" : "c0f99ddc-380f-4fab-b48d-08b0c89e885c",
      "zipcode" : null,
      "custom_field" : {},
      "lists" : null,
      "middle_name" : null,
      "contactable" : true,
      "country" : null,
      "address" : null,
      "linkedin" : null,
      "source" : "native_form",
      "next" : null,
      "mobile" : null,
      "state" : null,
      "previous" : null,
      "time_zone" : null,
      "org_id" : 1296005006,
      "status" : "subscribed",
      "first_name" : "David"
   }
}
EXPAND ↓

Note

1. Unsubscribe a contact
If you’d like to update a contact status use this API.

Copied Copy 
1
curl -H "fm-token:sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"email": "james.sampleton@sample.com","status":"unsubscribed"}' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓

View a Contact

This API allows you to view the details of a contact.

get
/mas/api/v1/contacts/[id]
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82"  -XGET "https://domain.freshmarketer.com/mas/api/v1/contacts/1"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
   "contact" : {
      "address" : null,
      "company" : null,
      "source" : "native_form",
      "language" : null,
      "twitter" : null,
      "status" : "subscribed",
      "created_at" : 1584706074000,
      "email" : "james.sampleton@sample.com",
      "subscriptions" : [],
      "time_zone" : null,
      "linkedin" : null,
      "updated_at" : 1584707971000,
      "cf_dropdown_values" : null,
      "source_id" : 1,
      "owner_id" : null,
      "uuid" : "e2b933c5-9769-4f64-8abb-f3495e07b561",
      "phone" : null,
      "previous" : null,
      "contactable" : false,
      "state" : null,
      "custom_field" : {
         "cf_producttype" : "saas",
         "cf_purchasedate" : "2020-03-19T18:30:00.000Z",
         "cf_totalamount" : 780.56
      },
      "id" : 1767727,
      "score" : null,
      "first_name" : "James",
      "next" : null,
      "fwMcrId" : null,
      "lists" : null,
      "zipcode" : null,
      "facebook" : null,
      "city" : null,
      "middle_name" : null,
      "last_name" : "Sampleton (sample)",
      "org_id" : 1296005006,
      "mobile" : null,
      "custom2" : null,
      "subscription_type" : [
         97
      ],
      "country" : null
   }
}
EXPAND ↓

Note

1. View contact by Email
This API allows you to view the details of a contact by Email id.

Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82"  -XGET "https://domain.freshmarketer.com/mas/api/v1/contacts/james.sampleton@sample.com"
EXPAND ↓

View all Contact

This API allows you to view the all contacts.

get
/mas/api/v1/contacts
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82"  -XGET "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
{
   "contacts" : [
      {
         "phone" : null,
         "custom2" : [],
         "subscriptions" : null,
         "last_name" : null,
         "middle_name" : null,
         "city" : null,
         "score" : null,
         "time_zone" : null,
         "mobile" : null,
         "address" : "Apto 1003 Torre 1",
         "previous" : null,
         "facebook" : null,
         "id" : 1767702,
         "fwMcrId" : null,
         "cf_dropdown_values" : null,
         "language" : null,
         "created_at" : 1584542655000,
         "first_name" : "Angela Acero / Gabriel Castellanos",
         "zipcode" : null,
         "status" : "subscribed",
         "email" : "aceroangela@yahoo.com",
         "contactable" : true,
         "org_id" : 1296005006,
         "lists" : null,
         "subscription_type" : [
            41,
            42,
            43,
            44
         ],
         "country" : null,
         "uuid" : "168fe148-9c7b-448f-bd7d-725146d0ddba",
         "linkedin" : null,
         "state" : null,
         "updated_at" : 1584555294000,
         "company" : null,
         "twitter" : null,
         "source" : "imported",
         "next" : null,
         "owner_id" : null,
         "custom_field" : {},
         "source_id" : 1
      },
      {
         "source_id" : 1,
         "custom_field" : {},
         "owner_id" : null,
         "next" : null,
         "source" : "imported",
         "twitter" : null,
         "company" : null,
         "updated_at" : 1584555294000,
         "state" : null,
         "linkedin" : null,
         "country" : null,
         "subscription_type" : [
            41,
            42,
            43,
            44
         ],
         "uuid" : "abaf63e4-5e3f-4c52-90b2-756210be473d",
         "email" : "james.sampleton@sample.com",
         "contactable" : true,
         "status" : "subscribed",
         "lists" : null,
         "org_id" : 1296005006,
         "zipcode" : null,
         "first_name" : "Jackeline Molano Bejarano",
         "created_at" : 1584542655000,
         "language" : null,
         "cf_dropdown_values" : null,
         "id" : 1767706,
         "fwMcrId" : null,
         "previous" : null,
         "facebook" : null,
         "address" : "Apto 1301 Torre 1",
         "mobile" : null,
         "time_zone" : null,
         "score" : null,
         "city" : null,
         "middle_name" : null,
         "last_name" : null,
         "subscriptions" : null,
         "custom2" : [],
         "phone" : null
      }
   ],
   "meta" : {
      "total_relation" : "EQUAL",
      "total_pages" : 193,
      "total_items" : 1925,
      "page_count" : 10,
      "current_page" : 1,
      "items_per_page" : 10
   }
}
EXPAND ↓

Get subscription types

This API allows you to get the all subscription types.

get
/mas/api/v1/email-types
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82"  -XGET "https://domain.freshmarketer.com/mas/api/v1/email-types?page=1&sort=updated_at%2Cdesc&size=30"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "meta": {
    "total_pages": 1,
    "page_count": 10,
    "items_per_page": 5,
    "total_items": 5,
    "current_page": 1,
    "total_relation": "EQUAL"
  },
  "email-type": [
    {
      "id": 44,
      "uuid": "987324cd-6d59-4aa3-9873-a036025e0c4b",
      "created_at": 1582798861000,
      "updated_at": 1582798861000,
      "name": "Conferences & Events",
      "description": "The latest updates on our events and conferences",
      "status": "activated"
    },
    {
      "id": 97,
      "uuid": "30a96ce6-2018-49b5-8987-59c2cabc9b7e",
      "created_at": 1584703432000,
      "updated_at": 1584703432000,
      "name": "new test type",
      "description": "dfsfsdfdsf",
      "status": "activated"
    },
    {
      "id": 41,
      "uuid": "f8b01ed8-bef7-46e6-9a5b-2e8a2aee9f72",
      "created_at": 1582798861000,
      "updated_at": 1582798861000,
      "name": "Newsletter",
      "description": "Occassional emails designed to notify you about everything - updates, promos, webinars, news, etc",
      "status": "activated"
    },
    {
      "id": 43,
      "uuid": "35c887f3-c559-46a7-97a4-f06ed50bb8ac",
      "created_at": 1582798861000,
      "updated_at": 1582798861000,
      "name": "Product Updates",
      "description": "A collection of our favorite blog content and updates on new features added to the product",
      "status": "activated"
    }
  ]
}
EXPAND ↓

Create a subscription type

This API allows you to create a subscription type.

POST
/mas/api/v1/email-types
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"name":"custom type","description":"desc"}' -X POST "https://domain.freshmarketer.com/mas/api/v1/email-types"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
{
   "email-type" : {
      "updated_at" : 1584703432000,
      "status" : "activated",
      "created_at" : 1584703432000,
      "name" : "custom type",
      "description" : "desc",
      "id" : 99,
      "uuid" : "d184adbb-d6e2-496b-9971-31c4850034fc"
   }
}
EXPAND ↓

Update a subscription type

This API allows you to update a subscription type.

PATCH
/mas/api/v1/email-types/[id]
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"name":"custom type updated","description":"desc"}' -X PATCH "https://domain.freshmarketer.com/mas/api/v1/email-types/99"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
{
   "email-type" : {
      "updated_at" : 1584710113828,
      "name" : "custom type updated",
      "status" : "activated",
      "created_at" : 1584703432000,
      "uuid" : "30a96ce6-2018-49b5-8987-59c2cabc9b7e",
      "description" : "desc",
      "id" : 99   }
}
EXPAND ↓

Update a Contact

This API allows you to update the information of a contact.

PATCH
/mas/api/v1/contacts/[id]
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -d '{"first_name":"mps","email":"samraj@test.com"}' -X PATCH "https://domain.freshmarketer.com/mas/api/v1/contacts/1"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
   "contact" : {
      "first_name" : "mps",
      "uuid" : "27faf72e-ef06-443e-9119-053d8a6ba112",
      "custom_field" : {},
      "email" : "samraj@test.com",
      "id" : 299418,
      "org_id" : 200002004,
      "source_id" : 1,
      "contactable" : true,
      "source" : "native_form",
      "created_at" : "2019-03-27T13:14:13.000+0000",
      "updated_at" : "2019-03-28T10:37:46.842+0000"
   }
}
EXPAND ↓

Delete a Contact

This API allows you to delete a contact.

delete
/mas/api/v1/contacts/[contact_id_or_email]
Sample code | Curl
Copied Copy 
1
curl -H fm-token:sfg999666t673t7t82" -X DELETE "https://domain.freshmarketer.com/mas/api/v1/contacts/1
EXPAND ↓
Response 
1
true
EXPAND ↓

Note

1. Delete a contact By Email
This API allows you to delete a contact by Email id.

Copied Copy 
1
curl -H fm-token:sfg999666t673t7t82" -X DELETE "https://domain.freshmarketer.com/mas/api/v1/contacts/james.sampleton@sample.com
EXPAND ↓

Add a list

This API allows you to create a list.

post
/mas/api/v1/lists
Sample code | Curl
Copied Copy 
1
curl -H fm-token:sfg999666t673t7t82  -H "Content-Type: application/json" -d '{"name": "apitestlist", "source": "native_form", "source_id": 1, "type": "fixed"}' -X POST "https://domain.freshmarketer.com/mas/api/v1/lists"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "list": {
    "id": 11279,
    "uuid": "2c93feed-68af-4dff-a68b-035b28b59996",
    "name": "apitestlist",
    "source": "native_form",
    "type": "fixed",
    "status": "active",
    "org_id": 365504,
    "created_at": 1584712192454,
    "updated_at": 1584712192454,
    "owner_id": null,
    "source_id": 1,
    "folder_id": null,
    "no_of_subscribers": 0
  }
}
EXPAND ↓

Get all lists

This API allows you to get all lists.

get
/mas/api/v1/lists
Sample code | Curl
Copied Copy 
1
curl -H fm-token:sfg999666t673t7t82 -XGET "https://domain.freshmarketer.com/mas/api/v1/lists"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
  "meta": {
    "total_pages": 21,
    "page_count": 10,
    "items_per_page": 10,
    "total_items": 201,
    "current_page": 1,
    "total_relation": "EQUAL"
  },
  "lists": [
    {
      "id": 1,
      "uuid": "f27-441d-4a69-a0ad-3867d2447999",
      "created_at": 1537859967000,
      "updated_at": 1537859967000,
      "owner_id": 365910,
      "source_id": 1,
      "name": "test list",
      "source": "imported",
      "type": "fixed",
      "deleted": false,
      "subscribers": null,
      "no_of_subscribers": 0,
      "status": "active",
      "folder_id": null,
      "folder_name": null
    },
    {
      "id": 2,
      "uuid": "9e82e97d-f57d-47a6-a4f1-71f39923e232",
      "created_at": 1537859983000,
      "updated_at": 1537859983000,
      "owner_id": 365505,
      "source_id": 1,
      "name": "FM Team",
      "source": "imported",
      "type": "fixed",
      "deleted": false,
      "subscribers": null,
      "no_of_subscribers": 0,
      "status": "active",
      "folder_id": null,
      "folder_name": null
    }
  ]
}
EXPAND ↓

Add a contact to list

This API allows you to add a contact to list.

PUT
/mas/api/v1/contacts
Sample code | Curl
Copied Copy 
1
curl -H "fm-token:sfg999666t673t7t82"  -H "Content-Type: application/json" -d '{"status":"subscribed","first_name":"James", "email": "james.sampleton@sample.com", "last_name":"Sampleton (sample)", "mobile_number":"1-926-555-9503","lists":[525,524] ,"custom_field": {"cf_producttype": "saas","cf_purchasedate":"2020-03-19T18:30:00.000Z","cf_totalamount":780.56} }' -X PUT "https://domain.freshmarketer.com/mas/api/v1/contacts"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "contact": {
    "id": 1767729,
    "uuid": "119a8a93-e4b7-4cb3-9472-c0a09dc689cc",
    "email": "james.sampleton@sample.com",
    "phone": null,
    "mobile": null,
    "fwMcrId": null,
    "facebook": null,
    "twitter": null,
    "linkedin": null,
    "company": null,
    "address": null,
    "city": null,
    "state": null,
    "zipcode": null,
    "country": null,
    "score": null,
    "source": "native_form",
    "source_id": 1,
    "status": "subscribed",
    "contactable": true,
    "custom2": [],
    "previous": null,
    "language": null,
    "next": null,
    "subscriptions": null,
    "cf_dropdown_values": {},
    "lists": [
      525,
      524
    ],
    "org_id": 1296005006,
    "created_at": 1584709579000,
    "updated_at": 1584710737436,
    "owner_id": null,
    "first_name": "James",
    "middle_name": null,
    "last_name": "Sampleton (sample)",
    "time_zone": null,
    "subscription_type": [
      97,
      41,
      42,
      43,
      44
    ],
    "custom_field": {
      "cf_totalamount": 780.56,
      "cf_purchasedate": "2020-03-19T18:30:00.000Z",
      "cf_producttype": "saas"
    }
  }
}
EXPAND ↓

Get contacts in a list

This API allows you to get contacts in a list.

get
/mas/api/v1/contacts?list_id=[list_id]&page=1&size=30
Sample code | Curl
Copied Copy 
1
curl -H fm-token:sfg999666t673t7t82 -XGET "https://domain.freshmarketer.com/mas/api/v1/contacts?list_id=526&page=1&size=30"
EXPAND ↓
Response 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
{
   "meta" : {
      "page_count" : 30,
      "total_items" : 5,
      "total_pages" : 1,
      "items_per_page" : 5,
      "total_relation" : "EQUAL",
      "current_page" : 1
   },
   "contacts" : [
      {
         "time_zone" : null,
         "language" : null,
         "status" : "subscribed",
         "score" : null,
         "previous" : null,
         "fwMcrId" : null,
         "email" : "thaveethu+1@osmetrics.com",
         "subscription_type" : [
            41,
            42,
            43,
            44
         ],
         "updated_at" : 1583936916000,
         "phone" : null,
         "owner_id" : null,
         "first_name" : null,
         "last_name" : null,
         "next" : null,
         "address" : null,
         "cf_dropdown_values" : null,
         "uuid" : "84acea14-46bc-4e00-90b5-b1ff93a53101",
         "linkedin" : null,
         "contactable" : true,
         "twitter" : null,
         "org_id" : 1296005006,
         "id" : 1767628,
         "zipcode" : null,
         "custom_field" : {
            "cf_mydate" : "2020-03-11T18:30:00.000Z",
            "cf_totalamount" : 132323.323
         },
         "city" : null,
         "company" : null,
         "custom2" : [],
         "state" : null,
         "facebook" : null,
         "middle_name" : null,
         "mobile" : null,
         "lists" : null,
         "created_at" : 1583936894000,
         "source_id" : 1,
         "source" : "imported",
         "country" : null,
         "subscriptions" : null
      },
      {
         "country" : null,
         "subscriptions" : null,
         "facebook" : null,
         "mobile" : null,
         "middle_name" : null,
         "lists" : null,
         "created_at" : 1583936894000,
         "source_id" : 1,
         "source" : "imported",
         "custom_field" : {
            "cf_totalamount" : 21212121,
            "cf_mydate" : "2020-03-13T18:30:00.000Z"
         },
         "company" : null,
         "city" : null,
         "custom2" : [],
         "state" : null,
         "id" : 1767629,
         "org_id" : 1296005006,
         "zipcode" : null,
         "contactable" : true,
         "twitter" : null,
         "next" : null,
         "address" : null,
         "cf_dropdown_values" : null,
         "uuid" : "3816192e-5f8b-4921-a041-e4160d3995c9",
         "linkedin" : null,
         "fwMcrId" : null,
         "email" : "thaveethu+2@osmetrics.com",
         "subscription_type" : [
            41,
            42,
            43,
            44
         ],
         "updated_at" : 1583936937000,
         "phone" : null,
         "owner_id" : null,
         "last_name" : null,
         "first_name" : null,
         "language" : null,
         "time_zone" : null,
         "status" : "subscribed",
         "score" : null,
         "previous" : null
      }
   ]
}
EXPAND ↓

Remove a contact from list

This API allows you to remove a contact from list.

PATCH
/mas/api/v1/lists/[list_id]/subscribers/[contact_id]/unsubscribe
Sample code | Curl
Copied Copy 
1
curl -H fm-token:sfg999666t673t7t82 -X PATCH "https://domain.freshmarketer.com/mas/api/v1/lists/526/subscribers/1767726/unsubscribe"
EXPAND ↓
Response 
1
200
EXPAND ↓

Transactional Email

A transactional email is a type of email that’s triggered by user action on a website. Some common examples of transactional emails include order shipment confirmations, account activation emails, password resets, invoices and receipts, and welcome emails.

ATTRIBUTE TYPE DESCRIPTION
id string UUID of the created for the Transactional Email
tokens JSON object Transaction Merge Tag Token
recipient string Email Id to whom the email needs to be sent

Trigger Transactional Email

This API allows you to trigger send your transactional email your configured to be sent if any validation error exists this API will notify you with the error response and on the success, an email will get added in the queue and get delivered.

post
/mas/api/v1//mail/transactional
Sample code | Curl
Copied Copy 
1
curl -H fm-token:"sfg999666t673t7t82" -H "Content-Type: application/json" -H "accept: application/json" -d '{"id":"3970a1b0-6e27-448a-adfc-0083db15b2fb", "tokens":{"design_token1":"Hi","design_token2":"Hello","design_token3":"World","subject_token1":"XYZ"}, "recipient":"james.sampleton@sample.com"}' -X POST "https://domain.freshmarketer.com/mas/api/v1/mail/transactional"
EXPAND ↓
Response 
1
2
3
4
"transactional_email":{
   "valid":true,
   "message": "Transactional Email Triggered Successfully"
 }
EXPAND ↓

Enter your domain and API key the CURL commands will become executable.