{"__v":10,"_id":"58196284266dc10f00e4745f","category":{"__v":0,"_id":"57f53fb368a53b2000e03f0f","project":"5588b8a2f6c18d0d005bba03","version":"5588b8a2f6c18d0d005bba06","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-10-05T18:00:19.547Z","from_sync":false,"order":0,"slug":"api","title":"REST API"},"parentDoc":null,"project":"5588b8a2f6c18d0d005bba03","user":"5588b847f6c18d0d005bba01","version":{"__v":15,"_id":"5588b8a2f6c18d0d005bba06","project":"5588b8a2f6c18d0d005bba03","createdAt":"2015-06-23T01:38:42.696Z","releaseDate":"2015-06-23T01:38:42.696Z","categories":["5588b8a3f6c18d0d005bba07","5588e9689cfea70d00371df3","5588f5921163180d00b64704","561598b121e9110d0078025a","5616f1c9d170d00d00189306","5616f5c3a410c90d00c6121e","561803dcf8c9632100ac7592","563667280441020d0000e9eb","5642570d9417b40d00c0fcd3","57bf5f02efe0050e00d50bd5","57f53fb368a53b2000e03f0f","57f55187440418170086325a","582e3afa72fd270f0006926d","5841faa973967b0f004b4a2b","58db348aa32c8419002433bb"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-11-02T03:50:28.415Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"curl --header \"X-API-Token: <your token>\" https://api.mixmax.com/v1/contacts","language":"curl"}]},"method":"get","results":{"codes":[{"name":"","code":"{\n  \"results\": [\n    {\n      \"_id\": \"580aa34686e6e2194b25d79e\",\n      \"name\": \"Hello Mixmax\",\n      \"email\": \"hello:::at:::mixmax.com\",\n      \"userId\": \"kZYPwDDiGPTfQDj5n\",\n      \"contactId\": \"78abf1610ad702f1\",\n      \"analytics\": {\n        \"sent\": 100,\n        \"opened\": 90,\n        \"clicked\": 45,\n        \"downloaded\": 40,\n        \"replied\": 10,\n        \"delivered\": 100,\n        \"deliveredWithTrackedOpens\": 100,\n        \"deliveredWithTrackedLinks\": 100,\n        \"deliveredWithTrackedFiles\": 100,\n        \"percentages\": {\n          \"opened\": 90.0,\n          \"clicked\": 45.0,\n          \"downloaded\": 45.0,\n          \"replied\": 10.0\n        }\n      }\n    }\n  ],\n  \"next\": \"eyIkb2lkIjoiNTgwYWEzNDY4NmU2ZTIxOTRiMjVkNzllIn0\"\n}\n","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"586d9e463b18e60f007b961c","ref":"","in":"query","required":false,"desc":"Field to sort by. One of: `name`, `email`, `timestamp`, or `usedCount`","default":"(created date)","type":"string","name":"sort"},{"_id":"586efadf23f46d0f004281fc","ref":"","in":"query","required":false,"desc":"True to sort ascending (A-Z)","default":"false","type":"boolean","name":"sortAscending"},{"_id":"58754914bbad3f2500474d4d","ref":"","in":"query","required":false,"desc":"Optional search string. See below for format. If using search string, ALL contacts will be searched - even those shared with you.","default":"none","type":"string","name":"search"},{"_id":"588aa0c16a263e0f008eeef2","ref":"","in":"query","required":false,"desc":"True to include contacts shared with you. Can only be used when also using `search=` due to current performance limitations.","default":"false","type":"boolean","name":"includeShared"},{"_id":"588daa75e320233700cfc7e8","ref":"","in":"query","required":false,"desc":"Fields to expand in comma separated form. Currently supporting 'firstName' and 'lastName' and 'groups'.","default":"","type":"string","name":"expand"},{"_id":"58dda8aa75b5b20f00fa64b5","ref":"","in":"query","required":false,"desc":"Include analytics in the response","default":"false","type":"boolean","name":"withAnalytics"},{"_id":"58e44ead2aee6b0f00443ef0","ref":"","in":"query","required":false,"desc":"A string describing the analytics date range. One of 'today', 'yesterday', 'last7', 'thisWeek', 'lastWeek', 'last30', 'thisMonth', 'lastMonth', 'last12Months', 'thisYear', 'lastYear', 'allTime' or 'specific'.","default":"last30","type":"string","name":"dates"},{"_id":"58e44ead2aee6b0f00443eef","ref":"","in":"query","required":false,"desc":"The client's timezone offset, in minutes. Used to determine date ranges.","default":"","type":"int","name":"timezoneOffset"},{"_id":"58e44ead2aee6b0f00443eee","ref":"","in":"query","required":false,"desc":"When `dates` is 'specific', the lower bound (in ms).","default":"","type":"timestamp","name":"since"},{"_id":"58e44ead2aee6b0f00443eed","ref":"","in":"query","required":false,"desc":"When `dates` is 'specific', the upper bound (in ms).","default":"","type":"timestamp","name":"until"}],"url":"/v1/contacts"},"isReference":true,"order":10,"body":"A Mixmax contact is automatically created for every person you communicate with in Mixmax. Contacts are also synced from Google Contacts and Salesforce lists automatically.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Email addresses can be associated with only one contact\",\n  \"body\": \"Currently a contact can only have one email address, and that email address cannot be used for another contact.\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"_id\",\n    \"0-1\": \"*String*\",\n    \"0-2\": \"Unique ID\",\n    \"1-0\": \"userId\",\n    \"1-1\": \"*String*\",\n    \"1-2\": \"Your user id\",\n    \"2-0\": \"email\",\n    \"2-1\": \"*String*\",\n    \"2-2\": \"Email address for the contact. Addresses are always lowercase. This is unique per user - there will only ever be one contact per email address per Mixmax user. Can be specified as a single email or as a String list of comma-separated emails.\",\n    \"3-0\": \"name\",\n    \"3-1\": \"*String*\",\n    \"3-2\": \"Name for the contact, or null if it isn't set\",\n    \"4-0\": \"timestamp\",\n    \"4-1\": \"*Timestamp*\",\n    \"4-2\": \"Unix timestamp of when the contact was last emailed\",\n    \"6-0\": \"contactId\",\n    \"6-1\": \"*String*\",\n    \"6-2\": \"Google ID that this contact is associated with, if a contact exists in Google Contacts for this same email address.\",\n    \"7-0\": \"salesforceId\",\n    \"7-1\": \"*String*\",\n    \"7-2\": \"Salesforce ID that this contact is associated with, if a contact exists in Salesforce (either contact or a lead) for this same email address.\",\n    \"8-0\": \"meta\",\n    \"8-1\": \"*Object*\",\n    \"8-2\": \"Contact variables from any source (ex. Salesforce) that are used to populate sequences and templates variables.\\n\\nIf expand is set in the query with 'firstName' or 'lastName', then it will populate 'First Name' and 'Last Name' metadata properties if they not exist already. The values for these fields will be derived from the Contact's name.\",\n    \"5-0\": \"usedCount\",\n    \"5-1\": \"*Number*\",\n    \"5-2\": \"The number of times this person was contacted.\",\n    \"9-0\": \"analytics\",\n    \"9-1\": \"*Object*\",\n    \"9-2\": \"Analytics for the contact.\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Searching\"\n}\n[/block]\nThe search string will match either email or the name of the contact. In addition, the following search operators are supported (see below). Multiple-word values for search operators must be escaped in quotes (e.g. name:\"brad vogel\").\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"What you can search by\",\n    \"h-1\": \"Search operator & example\",\n    \"0-0\": \"*The contact's email address*\",\n    \"1-0\": \"*The contact's full name*\",\n    \"0-1\": \"`email:hello@mixmax.com` or `email:hello@mixmax.com,hello+1@mixmax.com`\\n\\nExact email required. Matches case-insensitively.\",\n    \"1-1\": \"`name:Mixmax`\\n\\nPartial match on contact name. Matches case-insensitively. Only one `name:` search operator supported.\",\n    \"2-0\": \"*Groups the contact is in*\",\n    \"2-1\": \"`groups:\\\"my group name\\\"`\\n\\nExact, case-sensitive match on group name. If multiple `group:` search operators passed they will be treated as an AND (i.e. contacts returned must be in all groups).\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]","excerpt":"Lists all your contacts in Mixmax (ie people you've emailed using Mixmax). Does not currently return contacts shared with you via shared contact groups (a performance limitiation).","slug":"contacts","type":"endpoint","title":"/contacts"}

get/contacts

Lists all your contacts in Mixmax (ie people you've emailed using Mixmax). Does not currently return contacts shared with you via shared contact groups (a performance limitiation).

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

sort:
string(created date)
Field to sort by. One of: `name`, `email`, `timestamp`, or `usedCount`
sortAscending:
booleanfalse
True to sort ascending (A-Z)
search:
stringnone
Optional search string. See below for format. If using search string, ALL contacts will be searched - even those shared with you.
includeShared:
booleanfalse
True to include contacts shared with you. Can only be used when also using `search=` due to current performance limitations.
expand:
string
Fields to expand in comma separated form. Currently supporting 'firstName' and 'lastName' and 'groups'.
withAnalytics:
booleanfalse
Include analytics in the response
dates:
stringlast30
A string describing the analytics date range. One of 'today', 'yesterday', 'last7', 'thisWeek', 'lastWeek', 'last30', 'thisMonth', 'lastMonth', 'last12Months', 'thisYear', 'lastYear', 'allTime' or 'specific'.
timezoneOffset:
integer
The client's timezone offset, in minutes. Used to determine date ranges.
since:
timestamp
When `dates` is 'specific', the lower bound (in ms).
until:
timestamp
When `dates` is 'specific', the upper bound (in ms).

Examples


Result Format


Documentation

A Mixmax contact is automatically created for every person you communicate with in Mixmax. Contacts are also synced from Google Contacts and Salesforce lists automatically. [block:callout] { "type": "warning", "title": "Email addresses can be associated with only one contact", "body": "Currently a contact can only have one email address, and that email address cannot be used for another contact." } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "_id", "0-1": "*String*", "0-2": "Unique ID", "1-0": "userId", "1-1": "*String*", "1-2": "Your user id", "2-0": "email", "2-1": "*String*", "2-2": "Email address for the contact. Addresses are always lowercase. This is unique per user - there will only ever be one contact per email address per Mixmax user. Can be specified as a single email or as a String list of comma-separated emails.", "3-0": "name", "3-1": "*String*", "3-2": "Name for the contact, or null if it isn't set", "4-0": "timestamp", "4-1": "*Timestamp*", "4-2": "Unix timestamp of when the contact was last emailed", "6-0": "contactId", "6-1": "*String*", "6-2": "Google ID that this contact is associated with, if a contact exists in Google Contacts for this same email address.", "7-0": "salesforceId", "7-1": "*String*", "7-2": "Salesforce ID that this contact is associated with, if a contact exists in Salesforce (either contact or a lead) for this same email address.", "8-0": "meta", "8-1": "*Object*", "8-2": "Contact variables from any source (ex. Salesforce) that are used to populate sequences and templates variables.\n\nIf expand is set in the query with 'firstName' or 'lastName', then it will populate 'First Name' and 'Last Name' metadata properties if they not exist already. The values for these fields will be derived from the Contact's name.", "5-0": "usedCount", "5-1": "*Number*", "5-2": "The number of times this person was contacted.", "9-0": "analytics", "9-1": "*Object*", "9-2": "Analytics for the contact." }, "cols": 3, "rows": 10 } [/block] [block:api-header] { "type": "basic", "title": "Searching" } [/block] The search string will match either email or the name of the contact. In addition, the following search operators are supported (see below). Multiple-word values for search operators must be escaped in quotes (e.g. name:"brad vogel"). [block:parameters] { "data": { "h-0": "What you can search by", "h-1": "Search operator & example", "0-0": "*The contact's email address*", "1-0": "*The contact's full name*", "0-1": "`email:hello@mixmax.com` or `email:hello@mixmax.com,hello+1@mixmax.com`\n\nExact email required. Matches case-insensitively.", "1-1": "`name:Mixmax`\n\nPartial match on contact name. Matches case-insensitively. Only one `name:` search operator supported.", "2-0": "*Groups the contact is in*", "2-1": "`groups:\"my group name\"`\n\nExact, case-sensitive match on group name. If multiple `group:` search operators passed they will be treated as an AND (i.e. contacts returned must be in all groups)." }, "cols": 2, "rows": 3 } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}