https://spiceai.org/assets/js/042152cb.67684068.js

1"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([["118475"],{616317(e,n,t){t.r(n),t.d(n,{metadata:()=>s,default:()=>h,frontMatter:()=>r,contentTitle:()=>c,toc:()=>l,assets:()=>o});var s=JSON.parse('{"id":"components/data-connectors/imap","title":"IMAP Data Connector","description":"IMAP Data Connector Documentation","source":"@site/versioned_docs/version-2.0.x/components/data-connectors/imap.md","sourceDirName":"components/data-connectors","slug":"/components/data-connectors/imap","permalink":"/docs/v2.0/components/data-connectors/imap","draft":false,"unlisted":false,"editUrl":"https://github.com/spiceai/docs/edit/trunk/website/versioned_docs/version-2.0.x/components/data-connectors/imap.md","tags":[],"version":"2.0.x","frontMatter":{"title":"IMAP Data Connector","sidebar_label":"IMAP Data Connector","description":"IMAP Data Connector Documentation","pagination_prev":null},"sidebar":"docs","next":{"title":"Kafka Data Connector","permalink":"/docs/v2.0/components/data-connectors/kafka"}}'),i=t(474848),d=t(28453);let r={title:"IMAP Data Connector",sidebar_label:"IMAP Data Connector",description:"IMAP Data Connector Documentation",pagination_prev:null},c,o={},l=[{value:"Schema",id:"schema",level:2},{value:"Retrieving email body contents",id:"retrieving-email-body-contents",level:2},{value:"Configuration",id:"configuration",level:2},{value:"<code>from</code>

1",id:"from",level:3},{value:"<code>name</code>",id:"name",level:3},{value:"<code>params</code>",id:"params",level:3},{value:"Examples",id:"examples",level:2},{value:"Basic example",id:"basic-example",level:3},{value:"Secrets",id:"secrets",level:2},{value:"Cookbook",id:"cookbook",level:2}];function a(e){let n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,d.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.p,{children:"The IMAP Data Connector enables federated SQL query across emails stored in an IMAP email server."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"datasets:\n  - from: imap:[email protected]\n    name: emails\n    params:\n      imap_password: ${secrets:IMAP_PASSWORD}\n"})}),"\n",(0,i.jsx)(n.h2,{id:"schema",children:"Schema"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Field Name"}),(0,i.jsx)(n.th,{children:"Data Type"}),(0,i.jsx)(n.th,{children:"Nullable"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"date"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"Date64"})}),(0,i.jsx)(n.td,{children:"No"}),(0,i.jsx)(n.td,{children:"The date and time when the email was sent."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"subject"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"Utf8"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"The subject line of the email."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"from"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"List<Utf8>"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"The sender(s) of the email."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"to"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"List<Utf8>"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"The primary recipient(s) of the email."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"cc"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"List<Utf8>"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"The carbon copy recipient(s) of the email."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"bcc"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"List<Utf8>"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"The blind carbon copy recipient(s) of the email."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"reply_to"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"List<Utf8>"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"The email address(es) to which replies should be sent."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"message_id"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"Utf8"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"A unique identifier for the email message."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"in_reply_to"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"Utf8"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsxs)(n.td,{children:["The ",(0,i.jsx)(n.code,{children:"message_id"})," of the email this message is replying to, if applicable."]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"content"})}),(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"Utf8"})}),(0,i.jsx)(n.td,{children:"Yes"}),(0,i.jsx)(n.td,{children:"The raw email body of this message. Not retrieved when acceleration is disabled."})]})]})]}),"\n",(0,i.jsx)(n.p,{children:"If a MIME-encoded value is retrieved for a field, it is not decoded and the MIME-encoded value is returned in SQL queries."}),"\n",(0,i.jsxs)(n.p,{children:["Most fields are optional, and depend on the implementation of the specific IMAP server being connected to. For example, the IMAP RFC specifies the ",(0,i.jsx)(n.code,{children:"message_id"})," field SHOULD be supplied but the field is an optional field."]}),"\n",(0,i.jsxs)(n.p,{children:["For more information, refer to the ",(0,i.jsx)(n.a,{href:"https://www.rfc-editor.org/rfc/rfc2822#section-3.6",children:"IMAP R

1FC 2822 - Section 3.6"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"retrieving-email-body-contents",children:"Retrieving email body contents"}),"\n",(0,i.jsx)(n.p,{children:"When the IMAP Data Connector is used without acceleration, the email body will not be retrieved - only header/subject values. To load the email body contents, specify an acceleration:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"datasets:\n  - from: imap:[email protected]\n    name: emails\n    params:\n      imap_password: ${secrets:IMAP_PASSWORD}\n    acceleration:\n      enabled: true\n"})}),"\n",(0,i.jsxs)(n.p,{children:["With an acceleration enabled, the ",(0,i.jsx)(n.code,{children:"content"})," field will be populated with the complete email body including headers, without any decoding applied. This field could be used for post-processing the email, like retrieving custom header values or decoding MIME-encoded content."]}),"\n",(0,i.jsx)(n.admonition,{title:"Limitations",type:"warning",children:(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Email attachments are currently not parsed from the email body into separate dataset fields. To read email attachments, parse the multipart encodings from the ",(0,i.jsx)(n.code,{children:"content"})," field."]}),"\n"]})}),"\n",(0,i.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,i.jsx)(n.h3,{id:"from",children:(0,i.jsx)(n.code,{children:"from"})}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"from"})," field must contain the email address for the mailbox to connect to. For example, ",(0,i.jsx)(n.code,{children:"[email protected]"}),", or ",(0,i.jsx)(n.code,{children:"[email protected]"}),"."]}),"\n",(0,i.jsx)(n.h3,{id:"name",children:(0,i.jsx)(n.code,{children:"name"})}),"\n",(0,i.jsx)(n.p,{children:"The dataset name. This will be used as the table name within Spice."}),"\n",(0,i.jsx)(n.p,{children:"Example:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"datasets:\n  - from: imap:[email protected]\n    name: emails\n    params: ...\n"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-sql",children:"SELECT COUNT(*) FROM emails;\n"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-shell",children:"+----------+\n| count(*) |\n+----------+\n| 1234     |\n+----------+\n"})}),"\n",(0,i.jsxs)(n.p,{children:["The dataset name cannot be a ",(0,i.jsx)(n.a,{href:"../../reference/spicepod/keywords",children:"reserved keyword"}),"."]}),"\n",(0,i.jsx)(n.h3,{id:"params",children:(0,i.jsx)(n.code,{children:"params"})}),"\n",(0,i.jsx)(n.p,{children:"The IMAP connector supports the following connection and authentication parameters:"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Parameter Name"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"imap_username"})}),(0,i.jsxs)(n.td,{children:["Optional. The username to use for the IMAP connection. Defaults to the value of the ",(0,i.jsx)(n.code,{children:"from:"})," mailbox field."]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"imap_password"})}),(0,i.jsx)(n.td,{children:"Required. The password to use for the IMAP connection, in plaintext authentication mode."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"imap_host"})}),(0,i.jsx)(n.td,{children:"Optional. The host or IP address of the IMAP server to connect to. Not required for known connections like Outlook or Gmail."})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"imap_port"})}),(0,i.jsxs)(n.td,{children:["Optional. The port of the IMAP server to connect to. Defaults to ",(0,i.jsx)(n.code,{children:"993"}),"."]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"imap_mailbox"})}),(0,i.jsxs)(n.td,{children:["Optional. The mailbox to read mail from. Defaults to ",(0,i.jsx)(n.code,{children:"INBOX"}),", the standard email inbox."]})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"imap_ssl_mode"})}),(0,i.jsxs)(n.td,{children:["Optional. The IMAP SSL mode to use. Defaults to ",(0,i.jsx)(n.code,{children:"auto"}),", permitted values of ",(0,i.jsx)(n.code,{children:"tls"}),", ",(0,i.jsx)(n.code,{children:"starttls"}),", ",(0,i.jsx)(n.code,{children:"disabled"})," or ",(0,i.jsx)(n.code,{children:"auto"}),"."]})]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"examples",children:"Examples"}),"\n",(0,i.jsx)(n.h3,{id:"basic-example",children:"Basic example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-yaml",children:"datasets:\n  - from: imap:[email protected]\n    name: emails\n    params:\n      imap_host: mail.example.com\n      imap_password: ${ secrets:I

1MAP_PASSWORD }\n"})}),"\n",(0,i.jsx)(n.h2,{id:"secrets",children:"Secrets"}),"\n",(0,i.jsxs)(n.p,{children:["Spice integrates with multiple secret stores to help manage sensitive data securely. For detailed information on supported secret stores, refer to the ",(0,i.jsx)(n.a,{href:"../secret-stores/",children:"secret stores documentation"}),". Additionally, learn how to use referenced secrets in component parameters by visiting the ",(0,i.jsx)(n.a,{href:"../secret-stores/#using-secrets",children:"using referenced secrets guide"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"cookbook",children:"Cookbook"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["A cookbook recipe to configure IMAP as a data connector in Spice. ",(0,i.jsx)(n.a,{href:"https://github.com/spiceai/cookbook/tree/trunk/imap/#readme",children:"IMAP Data Connector"})]}),"\n"]})]})}function h(e={}){let{wrapper:n}={...(0,d.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(a,{...e})}):a(e)}},28453(e,n,t){t.d(n,{R:()=>r,x:()=>c});var s=t(296540);let i={},d=s.createContext(i);function r(e){let n=s.useContext(d);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:r(e.components),s.createElement(d.Provider,{value:n},e.children)}}}]);