{"__v":7,"_id":"581cd086bb096b0f002e61ca","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":14,"_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"],"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-04T18:16:38.974Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"curl","code":"curl --header \"X-API-Token: <your token>\" https://api.mixmax.com/v1/events"}]},"results":{"codes":[{"name":"","code":"{\n  \"results\": [{\n    \"_id\": \"581eafb6fbd4ec0e3dc7c13f\",\n    \"threadId\": \"15837d6d611913ca\",\n    \"subject\": \"testing events\",\n    \"timestamp\": 1478406070266,\n    \"recipientEmail\": \"hello:::at:::mixmax.com\",\n    \"recipientName\": \"Mixmax Hello\",\n    \"userId\": \"icELAcH6ft7EZnLYh\",\n    \"device\": {\n      \"os\": \"Mac OS X\",\n      \"program\": \"Chrome\",\n      \"isMobile\": false\n    },\n    \"location\": {\n      \"city\": \"Seattle\",\n      \"region\": \"Washington\",\n      \"country\": \"United States\"\n    },\n    \"object\": {\n      \"type\": \"file\",\n      \"title\": \"temp.js\"\n    },\n    \"action\": \"downloaded\",\n    \"recipients\": [{\n      \"email\": \"hello@mixmax.com\",\n      \"name\": \"Mixmax Hello\"\n    }]\n  }]\n}","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"581cd098d23be20f00e2bd35","ref":"","in":"query","required":false,"desc":"Optional search string. See below for format.","default":"none","type":"string","name":"search"}],"url":"/v1/events"},"isReference":true,"order":20,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Event types\"\n}\n[/block]\nThere are 5 types of events that can be returned. The type is returned as the `action` key on the event (for legacy purposes). To limit your query to only return only one type of event, use `type:` search operator.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Type of event\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`unopened`\",\n    \"0-1\": \"A (synthetic) event representing a message that has been sent but hasn't been opened. This event will *disappear* when the message is opened by all its recipients. There will only be one unopened event per message that will list all recipients and if any have already opened the message.\",\n    \"1-0\": \"`opened`\",\n    \"1-1\": \"An event representing a message that has been sent and opened by a recipient of that message. There will be one opened event per time the message was opened. It will contain details about where it was opened and on what device.\",\n    \"2-0\": \"`clicked`\",\n    \"2-1\": \"An event representing a link being clicked in an email. The name of the link (in the `<a>`) will be returned in the `object` property of the response.\",\n    \"3-0\": \"`downloaded`\",\n    \"4-0\": \"`replied`\",\n    \"3-1\": \"An event representing a [Mixmax Cloud Attachment](http://success.mixmax.com/article/45-cloud-hosted-attachments-e28094-unlimited-size-track-downloads) in the message being downloaded. The filename of the attachment will be returned in the `object` property of the response.\",\n    \"4-1\": \"An event representing a message being replied to.\",\n    \"5-0\": \"`meetinginvites:confirmed`\",\n    \"5-1\": \"An event representing when a meeting is confirmed.\",\n    \"6-0\": \"`poll:voted`\",\n    \"6-1\": \"An event representing when a poll is voted on.\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Searching\"\n}\n[/block]\nThe search string will search the subject of the messages and recipients, and return all events related to matching messages. If the search string is passed in enclosed in double quotes, it will be used for exact matching on the message subject. The search string can also can optionally contain search operators, documented below. Multiple-word values for search operators must be escaped in quotes (e.g. `template:\"my template\"`).\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"What you can search by\",\n    \"h-1\": \"Search operator & Example\",\n    \"0-0\": \"*Who the event relates to* \",\n    \"0-1\": \"`to:<email>`\\n\\nExact email required. Also searches 'cc' and 'bcc' recipients. Multiple `to:` operators are supported.\\n\\nExample: `to:hello@mixmax.com`.\",\n    \"1-0\": \"*Date range* \",\n    \"1-1\": \"`since:YYYY-MM-DD`\\n`until:YYYY-MM-DD`\\n\\nOnly one `since:` and one `until:` operator is supported.\\n\\nExample to search events in November: `since:2016-11-01 until:2016-11-30`\",\n    \"3-0\": \"*A template used in the message* \",\n    \"3-1\": \"`template:\\\"<name or title>\\\"`\\n\\nEvents for messages that used a certain template, given by title or name. The exact and unique title (or name) is required, otherwise the first template matching your search string will be used. Multi-word strings must be quoted. Only one `template:` operator is supported per query.\\n\\nExample: `template:\\\"sales pitch #2\\\"`\",\n    \"4-0\": \"*Messages that were sent in a sequence* \",\n    \"4-1\": \"`sequence:\\\"<name>\\\"`\\n\\nEvents for messages that were sent automatically as a part of a sequence. The exact name is required, otherwise the first sequence matching your search string still be used. Multi-word strings must be quoted. Only one `sequence:` operator is supported per query.\\n\\nExample: `sequence:\\\"sales leads batch 5\\\"`\",\n    \"5-0\": \"*Who the message was sent from* \",\n    \"5-1\": \"`from:myself`\\n`from:\\\"<team name>\\\"`\\n`from:<email address of team member>`\\n\\nEvents for messages sent from anyone on a team, from a particular team member, or special keyword `myself` to return your own events. Only only `from:` operator supported per query.\",\n    \"2-0\": \"*Type of event* \",\n    \"2-1\": \"`type:opened`\\n\\nReturn only one type of event (see types table above). Only one `type:` operator is supported per query.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response format\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This API does not currently support the `previous` paging parameter. It does, however, support `next` so you can page forward. It also does not support `fields`, so all fields are returned on the response.\"\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\": \"threadId\",\n    \"1-1\": \"*String*\",\n    \"1-2\": \"Gmail thread ID that relates to this message\",\n    \"2-0\": \"subject\",\n    \"2-1\": \"*String*\",\n    \"2-2\": \"Subject of the message\",\n    \"3-0\": \"timestamp\",\n    \"3-1\": \"*Timestamp*\",\n    \"3-2\": \"When the event occurred\",\n    \"4-0\": \"userId\",\n    \"4-1\": \"*String*\",\n    \"4-2\": \"ID of the user that this event is for. This will be your user id unless\",\n    \"6-0\": \"action\",\n    \"6-1\": \"*String*\",\n    \"6-2\": \"The type of event (the name `action` is for legacy reasons). This will be exactly one of the above event types.\",\n    \"10-0\": \"recipients\",\n    \"10-1\": \"*Array*\",\n    \"10-2\": \"Array of recipients of the message associated with this event\",\n    \"11-0\": \"recipients.email\",\n    \"11-1\": \"*String*\",\n    \"12-0\": \"recipients.name\",\n    \"12-1\": \"*String*\",\n    \"12-2\": \"Name of the recipient if it was known when sending the email. Otherwise, `null`.\",\n    \"11-2\": \"Email address\",\n    \"8-0\": \"recipientEmail\",\n    \"8-1\": \"*String*\",\n    \"9-0\": \"recipientName\",\n    \"9-1\": \"*String*\",\n    \"8-2\": \"Recipient email associated with this event\",\n    \"9-2\": \"Recipient name associated with this event, if known when sending the email. Otherwise, `null`.\",\n    \"13-0\": \"device\",\n    \"13-1\": \"*Object*\",\n    \"13-2\": \"If action=opened or downloaded, this includes information about device that opened the email\",\n    \"14-0\": \"location\",\n    \"14-1\": \"*Object*\",\n    \"14-2\": \"If action=opened or downloaded, this includes information about the location of the device that opened the email\",\n    \"15-0\": \"object\",\n    \"15-1\": \"*Object*\",\n    \"15-2\": \"If action=clicked or downloaded, this includes information about the link or attachment\",\n    \"5-0\": \"teamIds\",\n    \"5-1\": \"*Array*\",\n    \"5-2\": \"Array of team _ids that this event is shared with.\",\n    \"16-0\": \"object.type\",\n    \"16-1\": \"*String*\",\n    \"17-0\": \"object.title\",\n    \"17-1\": \"*String*\",\n    \"16-2\": \"The type of object (arbitrary string)\",\n    \"17-2\": \"The title of the object, used for searching\",\n    \"7-0\": \"actionName\",\n    \"7-1\": \"*String*\",\n    \"7-2\": \"Arbitrary description of the action\"\n  },\n  \"cols\": 3,\n  \"rows\": 18\n}\n[/block]","excerpt":"Retrieves events that are created for all activity on your communication: emails sent, opened, etc. These show up in the Mixmax Live Feed (https://app.mixmax.com/dashboard/live).","slug":"events","type":"get","title":"/events"}

get/events

Retrieves events that are created for all activity on your communication: emails sent, opened, etc. These show up in the Mixmax Live Feed (https://app.mixmax.com/dashboard/live).

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Query Params

search:
stringnone
Optional search string. See below for format.

Examples


Result Format


Documentation

[block:api-header] { "type": "basic", "title": "Event types" } [/block] There are 5 types of events that can be returned. The type is returned as the `action` key on the event (for legacy purposes). To limit your query to only return only one type of event, use `type:` search operator. [block:parameters] { "data": { "h-0": "Type of event", "h-1": "Description", "0-0": "`unopened`", "0-1": "A (synthetic) event representing a message that has been sent but hasn't been opened. This event will *disappear* when the message is opened by all its recipients. There will only be one unopened event per message that will list all recipients and if any have already opened the message.", "1-0": "`opened`", "1-1": "An event representing a message that has been sent and opened by a recipient of that message. There will be one opened event per time the message was opened. It will contain details about where it was opened and on what device.", "2-0": "`clicked`", "2-1": "An event representing a link being clicked in an email. The name of the link (in the `<a>`) will be returned in the `object` property of the response.", "3-0": "`downloaded`", "4-0": "`replied`", "3-1": "An event representing a [Mixmax Cloud Attachment](http://success.mixmax.com/article/45-cloud-hosted-attachments-e28094-unlimited-size-track-downloads) in the message being downloaded. The filename of the attachment will be returned in the `object` property of the response.", "4-1": "An event representing a message being replied to.", "5-0": "`meetinginvites:confirmed`", "5-1": "An event representing when a meeting is confirmed.", "6-0": "`poll:voted`", "6-1": "An event representing when a poll is voted on." }, "cols": 2, "rows": 7 } [/block] [block:api-header] { "type": "basic", "title": "Searching" } [/block] The search string will search the subject of the messages and recipients, and return all events related to matching messages. If the search string is passed in enclosed in double quotes, it will be used for exact matching on the message subject. The search string can also can optionally contain search operators, documented below. Multiple-word values for search operators must be escaped in quotes (e.g. `template:"my template"`). [block:parameters] { "data": { "h-0": "What you can search by", "h-1": "Search operator & Example", "0-0": "*Who the event relates to* ", "0-1": "`to:<email>`\n\nExact email required. Also searches 'cc' and 'bcc' recipients. Multiple `to:` operators are supported.\n\nExample: `to:hello@mixmax.com`.", "1-0": "*Date range* ", "1-1": "`since:YYYY-MM-DD`\n`until:YYYY-MM-DD`\n\nOnly one `since:` and one `until:` operator is supported.\n\nExample to search events in November: `since:2016-11-01 until:2016-11-30`", "3-0": "*A template used in the message* ", "3-1": "`template:\"<name or title>\"`\n\nEvents for messages that used a certain template, given by title or name. The exact and unique title (or name) is required, otherwise the first template matching your search string will be used. Multi-word strings must be quoted. Only one `template:` operator is supported per query.\n\nExample: `template:\"sales pitch #2\"`", "4-0": "*Messages that were sent in a sequence* ", "4-1": "`sequence:\"<name>\"`\n\nEvents for messages that were sent automatically as a part of a sequence. The exact name is required, otherwise the first sequence matching your search string still be used. Multi-word strings must be quoted. Only one `sequence:` operator is supported per query.\n\nExample: `sequence:\"sales leads batch 5\"`", "5-0": "*Who the message was sent from* ", "5-1": "`from:myself`\n`from:\"<team name>\"`\n`from:<email address of team member>`\n\nEvents for messages sent from anyone on a team, from a particular team member, or special keyword `myself` to return your own events. Only only `from:` operator supported per query.", "2-0": "*Type of event* ", "2-1": "`type:opened`\n\nReturn only one type of event (see types table above). Only one `type:` operator is supported per query." }, "cols": 2, "rows": 6 } [/block] [block:api-header] { "type": "basic", "title": "Response format" } [/block] [block:callout] { "type": "warning", "body": "This API does not currently support the `previous` paging parameter. It does, however, support `next` so you can page forward. It also does not support `fields`, so all fields are returned on the response." } [/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": "threadId", "1-1": "*String*", "1-2": "Gmail thread ID that relates to this message", "2-0": "subject", "2-1": "*String*", "2-2": "Subject of the message", "3-0": "timestamp", "3-1": "*Timestamp*", "3-2": "When the event occurred", "4-0": "userId", "4-1": "*String*", "4-2": "ID of the user that this event is for. This will be your user id unless", "6-0": "action", "6-1": "*String*", "6-2": "The type of event (the name `action` is for legacy reasons). This will be exactly one of the above event types.", "10-0": "recipients", "10-1": "*Array*", "10-2": "Array of recipients of the message associated with this event", "11-0": "recipients.email", "11-1": "*String*", "12-0": "recipients.name", "12-1": "*String*", "12-2": "Name of the recipient if it was known when sending the email. Otherwise, `null`.", "11-2": "Email address", "8-0": "recipientEmail", "8-1": "*String*", "9-0": "recipientName", "9-1": "*String*", "8-2": "Recipient email associated with this event", "9-2": "Recipient name associated with this event, if known when sending the email. Otherwise, `null`.", "13-0": "device", "13-1": "*Object*", "13-2": "If action=opened or downloaded, this includes information about device that opened the email", "14-0": "location", "14-1": "*Object*", "14-2": "If action=opened or downloaded, this includes information about the location of the device that opened the email", "15-0": "object", "15-1": "*Object*", "15-2": "If action=clicked or downloaded, this includes information about the link or attachment", "5-0": "teamIds", "5-1": "*Array*", "5-2": "Array of team _ids that this event is shared with.", "16-0": "object.type", "16-1": "*String*", "17-0": "object.title", "17-1": "*String*", "16-2": "The type of object (arbitrary string)", "17-2": "The title of the object, used for searching", "7-0": "actionName", "7-1": "*String*", "7-2": "Arbitrary description of the action" }, "cols": 3, "rows": 18 } [/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 }}