{"_id":"5616f792d170d00d00189313","user":"5588b847f6c18d0d005bba01","__v":18,"project":"5588b8a2f6c18d0d005bba03","version":{"_id":"5588b8a2f6c18d0d005bba06","project":"5588b8a2f6c18d0d005bba03","__v":15,"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"},"category":{"_id":"57f55187440418170086325a","__v":0,"version":"5588b8a2f6c18d0d005bba06","project":"5588b8a2f6c18d0d005bba03","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-10-05T19:16:23.805Z","from_sync":false,"order":1,"slug":"integrations","title":"Message Integrations"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-08T23:09:06.987Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":3,"body":"When a user pastes a URL on a new line in the editor, Mixmax looks for a Link Resolver that can handle that app. If one is found, Mixmax shows UX feedback that a link is being generated:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7Isf2CycS2OdCpFxC37F_Screen%20Shot%202015-10-11%20at%2011.38.12%20AM.png\",\n        \"Screen Shot 2015-10-11 at 11.38.12 AM.png\",\n        \"877\",\n        \"754\",\n        \"#3f7cdc\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nLink Resolvers are chosen based on a regex that each provides. So if you paste in a link to a GitHub Gist, Mixmax will look for a Link Resolver matching the Gist URL format, and then show feedback that it's trying to resolve the link:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ViQf8oNKRj6zhTxk4Rad_Screen%20Shot%202015-10-11%20at%2011.41.46%20AM.png\",\n        \"Screen Shot 2015-10-11 at 11.41.46 AM.png\",\n        \"955\",\n        \"969\",\n        \"#457ac9\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nIf the Link Resolver returns an HTML preview of that link, Mixmax will swap the link URL for the HTML. In this case, the Gist link resolver will fetch the Gist from GitHub and return a preview of it:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/npgc9qwNQP2wnUVyRf7Q_Screen%20Shot%202015-10-12%20at%207.30.29%20PM.png\",\n        \"Screen Shot 2015-10-12 at 7.30.29 PM.png\",\n        \"610\",\n        \"477\",\n        \"#41649f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Parameters for Link Resolvers\"\n}\n[/block]\nLet's dive in a bit on what each parameter means, and what is expected of you as the developer to build.\n\n## Regular expression\n\nRegular expression to match the URL that is pasted in. This is passed to the Javascript constructor `new RegExp()` as a string, so ensure that it is escaped properly. The regex must not permit spaces.\n\n## Resolver URL\n\nThe URL called when the user pastes a URL (or when they type a URL and press enter). See more  [information](/docs/integration-api-appendix#client-side-ajax-api-requests) about client-side requests in Mixmax.\n\nThis URL is called with the following querystring parameters (through an HTTP GET request):\n\n  * **user**: Email address of the Mixmax user.\n  * **url**: The url that the user pasted that matches the regex.\n\nThis URL is expected to return a JSON object with the following properties:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"body\",\n    \"0-1\": \"*String* \",\n    \"0-2\": \"Required. The HTML representation that is inserted into the message as a \\\"card\\\" (an immutable island of content in the editor). This can optionally have [variables](/docs/integration-api-appendix#variables-in-emails)\",\n    \"1-0\": \"subject\",\n    \"1-1\": \"*String*\",\n    \"1-2\": \"Optional (defaults to empty string). If this happens to be used inside an email message (as opposed to a Mixmax template or a Mixmax signature) that doesn’t already have a subject set, this will set the subject. For example, if the user is typing “/weather SF, CA” and presses enter, the command could automatically set the subject to “Live weather for SF, CA”\",\n    \"2-0\": \"raw\",\n    \"2-1\": \"*Boolean*\",\n    \"2-2\": \"Optional (defaults to `false`). True if the content should be inserted into the editor as raw HTML (i.e. not an immutable \\\"card\\\"). The user will be able to edit the content.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"You maybe also return HTTP `204` (No Content) if the URL can not be previewed. This is the same as returning `{body: \\\"\\\"}`.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Tutorial: Building Giphy previewer\"\n}\n[/block]\n(note: also see our [blog post](https://mixmax.com/blog/giphy-link-resolver))\n\nWe'll walk you through an example to add a Link Preview integration to preview Giphy links in the form [http://giphy.com/gifs/excited-the-office-yes-t3Mzdx0SA3Eis](http://giphy.com/gifs/excited-the-office-yes-t3Mzdx0SA3Eis)\n\n1. Git clone [https://github.com/mixmaxhq/giphy-example-link-resolver](https://github.com/mixmaxhq/giphy-example-link-resolver) \n2. Run `npm install` and `npm start`\n3. Restart Chrome in a special temporary mode so the self-signed HTTPS urls can be loaded. See [here](http://developer.mixmax.com/docs/integration-api-appendix#local-development-error-neterr_insecure_response).\n4. Verify it works by visiting https://localhost:9146/resolver?url=http%3A%2F%2Fgiphy.com%2Fgifs%2Fexcited-the-office-yes-t3Mzdx0SA3Eis in your browser. It should return json.\n5. Open up the [Mixmax Dashboard](https://app.mixmax.com/dashboard/settings/integrations), click Settings, click Integrations, and click Add Link Resolver.\n6. Enter the following for the parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Input name\",\n    \"h-1\": \"Value\",\n    \"0-0\": \"Description\",\n    \"0-1\": \"Giphy (giphy.com/gifs/*)\",\n    \"1-0\": \"Regular Expression\",\n    \"1-1\": \"giphy.com/gifs/[^\\\\/]+\\\\-[^\\\\/]+$\",\n    \"2-0\": \"Resolver URL\",\n    \"2-1\": \"https://localhost:9146/resolver\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n7. Refresh Gmail with Mixmax installed. Click Compose and paste a Giphy url such as http://giphy.com/gifs/excited-the-office-yes-t3Mzdx0SA3Eis on a new line.","excerpt":"","slug":"overview-link-resolvers","type":"basic","title":"Link Resolvers"}
When a user pastes a URL on a new line in the editor, Mixmax looks for a Link Resolver that can handle that app. If one is found, Mixmax shows UX feedback that a link is being generated: [block:image] { "images": [ { "image": [ "https://files.readme.io/7Isf2CycS2OdCpFxC37F_Screen%20Shot%202015-10-11%20at%2011.38.12%20AM.png", "Screen Shot 2015-10-11 at 11.38.12 AM.png", "877", "754", "#3f7cdc", "" ] } ] } [/block] Link Resolvers are chosen based on a regex that each provides. So if you paste in a link to a GitHub Gist, Mixmax will look for a Link Resolver matching the Gist URL format, and then show feedback that it's trying to resolve the link: [block:image] { "images": [ { "image": [ "https://files.readme.io/ViQf8oNKRj6zhTxk4Rad_Screen%20Shot%202015-10-11%20at%2011.41.46%20AM.png", "Screen Shot 2015-10-11 at 11.41.46 AM.png", "955", "969", "#457ac9", "" ] } ] } [/block] If the Link Resolver returns an HTML preview of that link, Mixmax will swap the link URL for the HTML. In this case, the Gist link resolver will fetch the Gist from GitHub and return a preview of it: [block:image] { "images": [ { "image": [ "https://files.readme.io/npgc9qwNQP2wnUVyRf7Q_Screen%20Shot%202015-10-12%20at%207.30.29%20PM.png", "Screen Shot 2015-10-12 at 7.30.29 PM.png", "610", "477", "#41649f", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Parameters for Link Resolvers" } [/block] Let's dive in a bit on what each parameter means, and what is expected of you as the developer to build. ## Regular expression Regular expression to match the URL that is pasted in. This is passed to the Javascript constructor `new RegExp()` as a string, so ensure that it is escaped properly. The regex must not permit spaces. ## Resolver URL The URL called when the user pastes a URL (or when they type a URL and press enter). See more [information](/docs/integration-api-appendix#client-side-ajax-api-requests) about client-side requests in Mixmax. This URL is called with the following querystring parameters (through an HTTP GET request): * **user**: Email address of the Mixmax user. * **url**: The url that the user pasted that matches the regex. This URL is expected to return a JSON object with the following properties: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "body", "0-1": "*String* ", "0-2": "Required. The HTML representation that is inserted into the message as a \"card\" (an immutable island of content in the editor). This can optionally have [variables](/docs/integration-api-appendix#variables-in-emails)", "1-0": "subject", "1-1": "*String*", "1-2": "Optional (defaults to empty string). If this happens to be used inside an email message (as opposed to a Mixmax template or a Mixmax signature) that doesn’t already have a subject set, this will set the subject. For example, if the user is typing “/weather SF, CA” and presses enter, the command could automatically set the subject to “Live weather for SF, CA”", "2-0": "raw", "2-1": "*Boolean*", "2-2": "Optional (defaults to `false`). True if the content should be inserted into the editor as raw HTML (i.e. not an immutable \"card\"). The user will be able to edit the content." }, "cols": 3, "rows": 3 } [/block] [block:callout] { "type": "info", "title": "", "body": "You maybe also return HTTP `204` (No Content) if the URL can not be previewed. This is the same as returning `{body: \"\"}`." } [/block] [block:api-header] { "type": "basic", "title": "Tutorial: Building Giphy previewer" } [/block] (note: also see our [blog post](https://mixmax.com/blog/giphy-link-resolver)) We'll walk you through an example to add a Link Preview integration to preview Giphy links in the form [http://giphy.com/gifs/excited-the-office-yes-t3Mzdx0SA3Eis](http://giphy.com/gifs/excited-the-office-yes-t3Mzdx0SA3Eis) 1. Git clone [https://github.com/mixmaxhq/giphy-example-link-resolver](https://github.com/mixmaxhq/giphy-example-link-resolver) 2. Run `npm install` and `npm start` 3. Restart Chrome in a special temporary mode so the self-signed HTTPS urls can be loaded. See [here](http://developer.mixmax.com/docs/integration-api-appendix#local-development-error-neterr_insecure_response). 4. Verify it works by visiting https://localhost:9146/resolver?url=http%3A%2F%2Fgiphy.com%2Fgifs%2Fexcited-the-office-yes-t3Mzdx0SA3Eis in your browser. It should return json. 5. Open up the [Mixmax Dashboard](https://app.mixmax.com/dashboard/settings/integrations), click Settings, click Integrations, and click Add Link Resolver. 6. Enter the following for the parameters: [block:parameters] { "data": { "h-0": "Input name", "h-1": "Value", "0-0": "Description", "0-1": "Giphy (giphy.com/gifs/*)", "1-0": "Regular Expression", "1-1": "giphy.com/gifs/[^\\/]+\\-[^\\/]+$", "2-0": "Resolver URL", "2-1": "https://localhost:9146/resolver" }, "cols": 2, "rows": 3 } [/block] 7. Refresh Gmail with Mixmax installed. Click Compose and paste a Giphy url such as http://giphy.com/gifs/excited-the-office-yes-t3Mzdx0SA3Eis on a new line.