https://docs.mia-platform.eu/assets/js/b5134b91.46a4a6cb.js

1"use strict";(self.webpackChunkmia_platform_docs=self.webpackChunkmia_platform_docs||[]).push([["16737"],{328638(e,n,s){s.r(n),s.d(n,{metadata:()=>i,default:()=>h,frontMatter:()=>o,contentTitle:()=>l,toc:()=>r,assets:()=>c});var i=JSON.parse('{"id":"runtime-components/plugins/mail-notification-service/usage","title":"Mail Service Usage","description":"The Mail Service accepts POST requests at the following paths:","source":"@site/versioned_docs/version-15.0.1/runtime-components/plugins/mail-notification-service/usage.md","sourceDirName":"runtime-components/plugins/mail-notification-service","slug":"/runtime-components/plugins/mail-notification-service/usage","permalink":"/docs/15.0.1/runtime-components/plugins/mail-notification-service/usage","draft":false,"unlisted":false,"tags":[],"version":"15.0.1","frontMatter":{"id":"usage","title":"Mail Service Usage","sidebar_label":"Usage"},"sidebar":"marketplace","previous":{"title":"Configuration","permalink":"/docs/15.0.1/runtime-components/plugins/mail-notification-service/configuration"},"next":{"title":"Overview","permalink":"/docs/15.0.1/runtime-components/plugins/mailchimp-notification-service/overview"}}'),t=s(474848),a=s(28453);let o={id:"usage",title:"Mail Service Usage",sidebar_label:"Usage"},l,c={},r=[{value:"Attachments",id:"attachments",level:2},{value:"Some examples",id:"some-examples",level:2},{value:"POST to /send with single receiver",id:"post-to-send-with-single-receiver",level:3},{value:"POST to /send/split-recipients",id:"post-to-sendsplit-recipients",level:3},{value:"POST to /send with an HTML message",id:"post-to-send-with-an-html-message",level:3},{value:"POST to /send with an attachment",id:"post-to-send-with-an-attachment",level:3}];function d(e){let n={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["The Mail Service accepts ",(0,t.jsx)(n.strong,{children:"POST"})," requests at the following paths:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:(0,t.jsx)(n.code,{children:"BASE_URL/send"})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"BASE_URL/send/split-recipients"}),": each receiver will see themselves as the single main receiver of the e-mail."]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["The request ",(0,t.jsx)(n.code,{children:"body"})," has to contain the following parameters:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"recipient"}),": string or array of strings with at least one e-mail address"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"subject"}),": string"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"sender"})," (or ",(0,t.jsx)(n.code,{children:"from"})," for ",(0,t.jsx)(n.a,{href:"#attachments",children:"multipart e-mail"}),"): string representing an e-mail address"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["Only one between ",(0,t.jsx)(n.code,{children:"sender"})," and ",(0,t.jsx)(n.code,{children:"from"})," is admitted, otherwise the request is rejected"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.p,{children:"Optionally you can include:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"cc"}),": array of strings"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"bcc"}),": array of strings"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"message"})," : string"]}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsxs)(n.p,{children:[(0,t.jsx)(n.code,{children:"htmlMessage"})," : string representing an html"]}),"\n"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["If the operation is successful, the API will respond with the ",(0,t.jsx)(n.code,{children:"200"})," status code and an empty response body."]}),"\n",(0,t.jsx)(n.h2,{id:"attachments",children:"Attachments"}),"\n",(0,t.jsx)(n.p,{children:"This service allows to send attachments too, with a slightly different body."}),"\n",(0,t.jsx)(n.p,{children:"There are two main differences with the previous examples:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:["the body has to be of type ",(0,t.jsx)(n.code,{children:"form-data"})]}),"\n",(0,t.jsxs)(n.li,{children:["the ",(0,t.jsx)(n.code,{children:"sender"})," field is replaced by the ",(0,t.jsx)(n.code,{children:"from"})," field"]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["Look at this ",(0,t.jsx)(n.a,{href:"#post-to-send-with-an-attachment",children:"example"})," for a practical explanation of an e-mail with attachment."]}),"\n",(0,t.jsx)(n.h2,{id:"some-examples",children:"Some examples"}),"\n",(0,t.jsx)(n.h3,{id:"post-to-send-with-single-receiver",children:"POST to /send with single receiver"}),"\n",(0,t.jsxs)(n.p,{children:["This is an example of the body of the POST to the ",(0,t.jsx)(n.code,{children:"/send"})," endpoint to send an e-mail from Alice (",(0,t.jsx)(n.code,{children:"[email protected]"}),") to Bob (",(0,t.jsx)(n.code,{children:"[email protected]"}),") and Carol (",(0,t.jsx)(n.code,{children:"[email protected]"}),") with subject ",(0,t.jsx)(n.code,{children:"The subject of the e-mail"})," and message ",(0,t.jsx)(n.code,{children:"This is an example."})," Dave (",(0,t.jsx)(n.code,{children:"[email protected]"}),") will receive the e-mail in ",(0,t.jsx)(n.em,{children:"cc"}),"."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "recipient": ["[email protected]", "[email protected]"],\n "subject": "The subject of the e-mail",\n "sender": "[email protected]",\n "cc": ["[email protected]"],\n "message": "This is an example."\n}\n'})}),"\n",(0,t.jsx)(n.admonition,{type:"info",children:(0,t.jsx)(n.p,{children:"Bob will know that also Carol is receiving the e-mail and viceversa."})}),"\n",(0,t.jsx)(n.h3,{id:"post-to-sendsplit-recipients",children:"POST to /send/split-recipients"}),"\n",(0,t.jsxs)(n.p,{children:["This is an example of the body of the POST to the ",(0,t.jsx)(n.code,{children:"/send/split-recipients"})," endpoint to send two different e-mails from Alice (",(0,t.jsx)(n.code,{children:"[email protected]"}),") with subject ",(0,t.jsx)(n.code,{children:"The subject of the e-mail"})," and message ",(0,t.jsx)(n.code,{children:"This is an example."})," The first e-mail will be sent to Bob (",(0,t.jsx)(n.code,{children:"[email protected]"}),") and the second one will be sent to Carol (",(0,t.jsx)(n.code,{children:"[email protected]"}),"). Each recipient will not see that the e-mail was also sent to the other recipient."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "recipient": ["[email protected]", "[email protected]"],\n "subject": "The subject of the e-mail",\n "sender": "[email protected]",\n "cc": ["[email protected]"],\n "message": "This is an example."\n}\n'})}),"\n",(0,t.jsxs)(n.p,{children:["This is equivalent to making two different POST requests to ",(0,t.jsx)(n.code,{children:"/send"})," having the following bodies:"]}),"\n",(0,t.jsxs)(n.ol,{children:["\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"First request's body:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "recipient": "[email protected]",\n  "subject": "The subject of the e-mail",\n  "sender": "[email protected]",\n  "cc": ["[email protected]"],\n  "message": "This is an example."\n}\n'})}),"\n"]}),"\n",(0,t.jsxs)(n.li,{children:["\n",(0,t.jsx)(n.p,{children:"Second request's body:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "recipient": "[email protected]",\n  "subject": "The subject of the e-mail",\n  "sender": "[email protected]",\n  "cc": ["[email protected]"],\n  "message": "This is an example."\n}\n'})}),"\n"]}),"\n"]}),"\n",(0,t.jsx)(n.h3,{id:"post-to-send-with-an-html-message",children:"POST to /send with an HTML message"}),"\n",(0,t.jsx)(n.p,{children:"The service allows to send e-mails with an HTML content, which the receiver's client will render as HTML."}),"\n",(0,t.jsxs)(n.p,{children:["To send an HTML message you just have to put the e-mail content in the ",(0,t.jsx)(n.code,{children:"htmlMessage"})," field instead of using the regular ",(0,t.jsx)(n.code,{children:"message"})," field."]}),"\n",(0,t.jsxs)(n.p,{children:["Here is an example of how the ",(0,t.jsx)(n.code,{children:"/send"})," request would look like with an HTML template:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n  "recipient": "[email protected]",\n  "subject": "The subject of the e-mail",\n  "sender": "[email protected]",\n  "cc": ["[email protected]"],\n  "htmlMessage": "<!doctype html><html><head>  <meta name=\\\\"viewport\\\\" content=\\\\"width=device-width\\\\" />  <meta http-equiv=\\\\"Content-Type\\\\" content=\\\\"text/html; charset=UTF-8\\\\" />  <title>Simple Transactional e-mail</title>  ...  ...  ...</head><body class=\\\\"\\\\"> <span class=\\\\"preheader\\\\">This is preheader text. Some clients will show this text as a    preview.</span>  <table role=\\\\"presentation\\\\" border=\\\\"0\\\\" cellpadding=\\\\"0\\\\" cellspacing=\\\\"0\\\\" class=\\\\"body\\\\">    <tr>      <td>&nbsp;</td>      <td class=\\\\"container\\\\">        ...        ...      </td>      <td>&nbsp;</td>    </tr>  </table></body></html>"\n}\n'})}),"\n",(0,t.jsxs)(n.admonition,{type:"tip",children:[(0,t.jsx)(n.p,{children:"The HTML content must be converted to a string and should only contain inline styles to obtain the desired rendering."}),(0,t.jsxs)(n.p,{children:["You can still write external or embedded CSS and then use online tools like ",(0,t.jsx)(n.a,{href:"https://htmlemail.io/inline/",children:"this CSS Inliner"})," to convert all styles to inline styles."]}),(0,t.jsx)(n.p,{children:"You can also use your preferred template system to insert dynamic data into the HTML message. Please note that the Mail Notification Service does not provide any supp

1ort for templating as of today."})]}),"\n",(0,t.jsx)(n.h3,{id:"post-to-send-with-an-attachment",children:"POST to /send with an attachment"}),"\n",(0,t.jsx)(n.p,{children:"This service allows to send attachments too."}),"\n",(0,t.jsxs)(n.p,{children:["Here is an example of ",(0,t.jsx)(n.code,{children:"curl"})," with two attachments:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"curl --location --request POST 'mail-service/send' \\\n--form '[email protected]' \\\n--form '[email protected]' \\\n--form 'subject=The subject of the e-mail' \\\n--form 'message=The message of the e-mail' \\\n--form 'file1=@/path/to/the/file1'\n--form 'file2=@/path/to/the/file2'\n"})}),"\n",(0,t.jsx)(n.p,{children:"Here is an example of form data in node:"}),"\n",(0,t.jsx)(n.admonition,{type:"tip",children:(0,t.jsxs)(n.p,{children:["Since form data is part of JavaScript Web API, to use it under node you should install a library like ",(0,t.jsx)(n.a,{href:"https://www.npmjs.com/package/form-data",children:"form-data"}),"."]})}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-javascript",children:"const fs = require('fs')\nconst FormData = require('form-data')\n\nconst formData = new FormData()\nformData.append('from', '[email protected]')\nformData.append('recipient', '[email protected]')\nformData.append('subject', 'The subject of the e-mail')\nformData.append('message', 'The message of the e-mail')\n\nconst file1Stream = fs.createReadStream('path/to/the/file1')\nconst file2Stream = fs.createReadStream('path/to/the/file2')\nformData.append('file1', file1Stream)\nformData.append('file2', file2Stream)\n"})})]})}function h(e={}){let{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(d,{...e})}):d(e)}},28453(e,n,s){s.d(n,{R:()=>o,x:()=>l});var i=s(296540);let t={},a=i.createContext(t);function o(e){let n=i.useContext(a);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:o(e.components),i.createElement(a.Provider,{value:n},e.children)}}}]);