https://learn.emailengine.app/assets/js/067de786.782a2ff1.js

1"use strict";(globalThis.webpackChunkemailengine_temp=globalThis.webpackChunkemailengine_temp||[]).push([[5846],{28453(e,n,t){t.d(n,{R:()=>d,x:()=>r});var i=t(96540);const c={},s=i.createContext(c);function d(e){const n=i.useContext(s);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(c):e.components||c:d(e.components),i.createElement(s.Provider,{value:n},e.children)}},34924(e,n,t){t.r(n),t.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>h,frontMatter:()=>d,metadata:()=>i,toc:()=>o});const i=JSON.parse('{"id":"webhooks/accountinitialized","title":"accountInitialized","description":"Webhook event triggered when an email account completes its initial mailbox synchronization","source":"@site/docs/webhooks/accountinitialized.md","sourceDirName":"webhooks","slug":"/webhooks/accountinitialized","permalink":"/docs/webhooks/accountinitialized","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":16,"frontMatter":{"title":"accountInitialized","sidebar_position":16,"description":"Webhook event triggered when an email account completes its initial mailbox synchronization"},"sidebar":"docsSidebar","previous":{"title":"accountDeleted","permalink":"/docs/webhooks/accountdeleted"},"next":{"title":"authenticationError","permalink":"/docs/webhooks/authenticationerror"}}');var c=t(74848),s=t(28453);const d={title:"accountInitialized",sidebar_position:16,description:"Webhook event triggered when an email account completes its initial mailbox synchronization"},r="accountInitialized",a={},o=[{value:"When This Event is Triggered",id:"when-this-event-is-triggered",level:2},{value:"Technical Details",id:"technical-details",level:3},{value:"Payload Schema",id:"payload-schema",level:2},{value:"Top-Level Fields",id:"top-level-fields",level:3},{value:"Event Data Fields (<code>data</code> object)",id:"event-data-fields-data-object",level:3},{value:"Example Payload",id:"example-payload",level:2},{value:"Example Payload (Without Service URL)",id:"example-payload-without-service-url",level:2},{value:"Handling the Event",id:"handling-the-event",level:2},{value:"Event Sequence",id:"event-sequence",level:2},{value:"Re-initialization After Flush",id:"re-initialization-after-flush",level:3},{value:"Differences from Other Account Events",id:"differences-from-other-account-events",level:2},{value:"Related Events",id:"related-events",level:2},{value:"See Also",id:"see-also",level:2}];function l(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,s.R)(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(n.header,{children:(0,c.jsx)(n.h1,{id:"accountinitialized",children:"accountInitialized"})}),"\n",(0,c.jsxs)(n.p,{children:["The ",(0,c.jsx)(n.code,{children:"accountInitialized"})," webhook event is triggered when an email account reaches the ",(0,c.jsx)(n.code,{children:"connected"})," state for the first time. For an IMAP account that is after the first pass over its folders; for a Gmail API or Microsoft Graph account it is after the provider accepted the access token and returned the account profile. From this point the account is operational."]}),"\n",(0,c.jsx)(n.h2,{id:"when-this-event-is-triggered",children:"When This Event is Triggered"}),"\n",(0,c.jsxs)(n.p,{children:["The ",(0,c.jsx)(n.code,{children:"accountInitialized"})," event fires when:"]}),"\n",(0,c.jsxs)(n.ul,{children:["\n",(0,c.jsxs)(n.li,{children:["An account reaches the ",(0,c.jsx)(n.code,{children:"connected"})," state for the ",(0,c.jsx)(n.strong,{children:"first time"})," after being added"]}),"\n",(0,c.jsxs)(n.li,{children:["An account reaches the ",(0,c.jsx)(n.code,{children:"connected"})," state again after a ",(0,c.jsx)(n.a,{href:"/docs/api/put-v-1-account-account-flush",children:"flush"})]}),"\n"]}),"\n",(0,c.jsx)(n.p,{children:"It fires once per initialization cycle. Routine reconnections, restarts and recoveries from error states do not fire it again unless the account has been flushed in between."}),"\n",(0,c.jsx)(n.h3,{id:"technical-details",children:"Technical Details"}),"\n",(0,c.jsxs)(n.p,{children:["EmailEngine keeps a per-account counter of how many times the account has entered the ",(0,c.jsx)(n.code,{children:"connected"})," state. The counter is created at ",(0,c.jsx)(n.code,{children:"0"})," when the account is registered, and reset to ",(0,c.jsx)(n.code,{children:"0"})," by a flush. When the state becomes ",(0,c.jsx)(n.code,{children:"connected"})," and the counter moves from ",(0,c.jsx)(n.code,{children:"0"})," to ",(0,c.jsx)(n.code,{children:"1"}),", the event is sent."]}),"\n",(0,c.jsx)(n.h2,{id:"payload-schema",children:"Payload Schema"}),"\n",(0,c.jsx)(n.h3,{id:"top-level-fields",children:"Top-Level Fields"}),"\n",(0,c.jsxs)(n.table,{children:[(0,c.jsx)(n.thead,{children:(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.th,{children:"Field"}),(0,c.jsx)(n.th,{children:"Type"}),(0,c.jsx)(n.th,{children:"Required"}),(0,c.jsx)(n.th,{children:"Description"})]})}),(0,c.jsxs)(n.tbody,{children:[(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"serviceUrl"})}),(0,c.jsx)(n.td,{children:"string or null"}),(0,c.jsx)(n.td,{children:"Yes"}),(0,c.jsxs)(n.td,{children:["The configured EmailEngine service URL. ",(0,c.jsx)(n.code,{children:"null"})," when the ",(0,c.jsx)(n.code,{children:"serviceUrl"})," setting is empty"]})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"account"})}),(0,c.jsx)(n.td,{children:"string"}),(0,c.jsx)(n.td,{children:"Yes"}),(0,c.jsx)(n.td,{children:"The account ID that was initialized"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"date"})}),(0,c.jsx)(n.td,{children:"string"}),(0,c.jsx)(n.td,{children:"Yes"}),(0,c.jsx)(n.td,{children:"ISO 8601 timestamp when the webhook was generated"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"event"})}),(0,c.jsx)(n.td,{children:"string"}),(0,c.jsx)(n.td,{children:"Yes"}),(0,c.jsxs)(n.td,{children:["Always ",(0,c.jsx)(n.code,{children:"accountInitialized"})]})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"data"})}),(0,c.jsx)(n.td,{children:"object"}),(0,c.jsx)(n.td,{children:"Yes"}),(0,c.jsx)(n.td,{children:"Event data object"})]})]})]}),"\n",(0,c.jsxs)(n.h3,{id:"event-data-fields-data-object",children:["Event Data Fields (",(0,c.jsx)(n.code,{children:"data"})," object)"]}),"\n",(0,c.jsxs)(n.table,{children:[(0,c.jsx)(n.thead,{children:(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.th,{children:"Field"}),(0,c.jsx)(n.th,{children:"Type"}),(0,c.jsx)(n.th,{children:"Required"}),(0,c.jsx)(n.th,{children:"Description"})]})}),(0,c.jsx)(n.tbody,{children:(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"initialized"})}),(0,c.jsx)(n.td,{children:"boolean"}),(0,c.jsx)(n.td,{children:"Yes"}),(0,c.jsxs)(n.td,{children:["Always ",(0,c.jsx)(n.code,{children:"true"})]})]})})]}),"\n",(0,c.jsxs)(n.p,{children:["There is no event ID in the body. EmailEngine sends it in the ",(0,c.jsx)(n.code,{children:"X-EE-Wh-Event-Id"})," request header, which is what to deduplicate on. See ",(0,c.jsx)(n.a,{href:"/docs/webhooks/overview#delivery-and-retries",children:"Delivery and Retries"}),"."]}),"\n",(0,c.jsx)(n.h2,{id:"example-payload",children:"Example Payload"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-json",children:'{\n  "serviceUrl": "https://emailengine.example.com",\n  "account": "user123",\n  "date": "2025-10-17T06:50:45.321Z",\n  "event": "accountInitialized",\n  "data": {\n    "initialized": true\n  }\n}\n'})}),"\n",(0,c.jsx)(n.h2,{id:"example-payload-without-service-url",children:"Example Payload (Without Service URL)"}),"\n",(0,c.jsx)(n.p,{children:"When no service URL is configured:"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-json",children:'{\n  "serviceUrl": null,\n  "account": "gmail-user456",\n  "date": "2025-10-17T08:16:15.000Z",\n  "event": "accountInitialized",\n  "data": {\n    "initialized": true\n  }\n}\n'})}),"\n",(0,c.jsx)(n.h2,{id:"handling-the-event",children:"Handling the Event"}),"\n",(0,c.jsx)(n.p,{children:"This is the point at which the account's folders and messages can be listed through the API, so it is where work that needs mailbox data belongs:"}),"\n",(0,c.jsx)(n.pre,{children:(0,c.jsx)(n.code,{className:"language-javascript",children:"async function handleAccountInitialized(event) {\n  const { account, date } = event;\n\n  await db.accounts.update({\n    where: { emailEngineId: account },\n    data: { status: 'active', initializedAt: new Date(date) }\n  });\n\n  // The folder listing is available from here on\n  const response = await fetch(\n    `https://emailengine.example.com/v1/account/${account}/mailboxes`,\n    { headers: { Authorization: `Bearer ${process.env.EE_TOKEN}` } }\n  );\n  const { mailboxes } = await response.json();\n  await cacheFolders(account, mailboxes);\n}\n"})}),"\n",(0,c.jsx)(n.h2,{id:"event-sequence",children:"Event Sequence"}),"\n",(0,c.jsx)(n.p,{children:"When a new account is added, webhooks arrive in this order:"}),"\n",(0,c.jsxs)(n.ol,{children:["\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.strong,{children:(0,c.jsx)(n.code,{children:"accountAdded"})})," - Account configuration is stored"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.strong,{children:(0,c.jsx)(n.code,{children:"authenticationSuccess"})})," - The mail server or provider accepted the credentials"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.strong,{children:(0,c.jsx)(n.code,{children:"accountInitialized"})})," - The account reached ",(0,c.jsx)(n.code,{children:"connected"})," (this event)"]}),"\n"]}),"\n",(0,c.jsxs)(n.p,{children:["For an IMAP account the first pass over the folders separates the last two. For a Gmail API or Microsoft Graph account both are sent during initialization, in the same order. Before EmailEngine 2.80.0 the API-based accounts sent ",(0,c.jsx)(n.code,{children:"accountInitialized"})," first; do not depend on the order between the two if you support older releases."]}),"\n",(0,c.jsx)(n.h3,{id:"re-initialization-after-flush",children:"Re-initialization After Flush"}),"\n",(0,c.jsxs)(n.p,{children:["The ",(0,c.jsx)(n.a,{href:"/docs/api/put-v-1-account-account-flush",children:"Flush Account API"})," resets the connection counter to ",(0,c.jsx)(n.code,{children:"0"})," and discards the account's mailbox listing and sync state, so:"]}),"\n",(0,c.jsxs)(n.ol,{children:["\n",(0,c.jsx)(n.li,{children:"The account disconnects and re-syncs from the current point in t

1ime"}),"\n",(0,c.jsxs)(n.li,{children:["A new ",(0,c.jsx)(n.code,{children:"accountInitialized"})," event fires when it reaches ",(0,c.jsx)(n.code,{children:"connected"})," again"]}),"\n"]}),"\n",(0,c.jsx)(n.p,{children:"Flushing is the way to re-run the initial sync after a configuration change without deleting and re-adding the account."}),"\n",(0,c.jsx)(n.h2,{id:"differences-from-other-account-events",children:"Differences from Other Account Events"}),"\n",(0,c.jsxs)(n.table,{children:[(0,c.jsx)(n.thead,{children:(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.th,{children:"Event"}),(0,c.jsx)(n.th,{children:"When Triggered"}),(0,c.jsx)(n.th,{children:"What It Means"})]})}),(0,c.jsxs)(n.tbody,{children:[(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"accountAdded"})}),(0,c.jsx)(n.td,{children:"After account creation"}),(0,c.jsx)(n.td,{children:"Account config is stored, connection not yet attempted"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"authenticationSuccess"})}),(0,c.jsx)(n.td,{children:"After successful authentication"}),(0,c.jsx)(n.td,{children:"Account can connect to mail server"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"accountInitialized"})}),(0,c.jsxs)(n.td,{children:["On the first ",(0,c.jsx)(n.code,{children:"connected"})," state"]}),(0,c.jsx)(n.td,{children:"Account is operational (this event)"})]}),(0,c.jsxs)(n.tr,{children:[(0,c.jsx)(n.td,{children:(0,c.jsx)(n.code,{children:"accountDeleted"})}),(0,c.jsx)(n.td,{children:"When account is removed"}),(0,c.jsx)(n.td,{children:"Account has been deleted from EmailEngine"})]})]})]}),"\n",(0,c.jsx)(n.h2,{id:"related-events",children:"Related Events"}),"\n",(0,c.jsxs)(n.ul,{children:["\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/webhooks/accountadded",children:"accountAdded"})," - Triggered when account is first registered"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/webhooks/authenticationsuccess",children:"authenticationSuccess"})," - Triggered when authentication succeeds"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/webhooks/authenticationerror",children:"authenticationError"})," - Triggered when authentication fails"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/webhooks/connecterror",children:"connectError"})," - Triggered when the connection fails before authentication"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/webhooks/accountdeleted",children:"accountDeleted"})," - Triggered when an account is removed"]}),"\n"]}),"\n",(0,c.jsx)(n.h2,{id:"see-also",children:"See Also"}),"\n",(0,c.jsxs)(n.ul,{children:["\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/webhooks/overview",children:"Webhooks Overview"})," - Configuring the webhook URL and the ",(0,c.jsx)(n.code,{children:"webhookEvents"})," allowlist"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/accounts/managing-accounts",children:"Account Management"})," - Account states and the lifecycle around them"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/api/post-v-1-account",children:"Create Account API"})," - Registering the account this event follows"]}),"\n",(0,c.jsxs)(n.li,{children:[(0,c.jsx)(n.a,{href:"/docs/api/put-v-1-account-account-flush",children:"Flush Account API"})," - Re-running the initial sync and this event"]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,c.jsx)(n,{...e,children:(0,c.jsx)(l,{...e})}):l(e)}}}]);