Skip to main content

accountAdded

The accountAdded webhook event is triggered when a new email account is registered with EmailEngine. It is the first event in the account lifecycle and means the account configuration has been accepted and stored. Nothing has been connected yet.

When This Event is Triggered​

The accountAdded event fires once, when an account ID that EmailEngine has not seen before is registered:

The event is sent by the main process after the account has been assigned to a worker and before that worker attempts a connection. Authentication has not been verified at this point.

Re-registering an account ID that already exists does not fire it again. A POST /v1/account for an existing account, or a hosted-form re-authorization of one, updates the stored account and reconnects it instead. The lifecycle events that follow a fresh registration are described under Event Sequence.

Like every event, it is delivered only if accountAdded or * is in webhookEvents. See Webhooks Overview for the allowlist.

Payload Schema​

Top-Level Fields​

FieldTypeRequiredDescription
serviceUrlstring or nullYesThe configured EmailEngine service URL. null when the serviceUrl setting is empty
accountstringYesThe account ID that was registered
datestringYesISO 8601 timestamp when the webhook was generated
eventstringYesAlways accountAdded
dataobjectYesEvent data object

Event Data Fields (data object)​

FieldTypeRequiredDescription
accountstringYesThe account ID, the same value as the top-level account field

There is no event ID in the body. EmailEngine sends it in the X-EE-Wh-Event-Id request header, which is what to deduplicate on. See Delivery and Retries.

Example Payload​

{
  "serviceUrl": "https://emailengine.example.com",
  "account": "user123",
  "date": "2025-10-17T06:49:22.157Z",
  "event": "accountAdded",
  "data": {
    "account": "user123"
  }
}

Example Payload (Without Service URL)​

When no service URL is configured:

{
  "serviceUrl": null,
  "account": "gmail-user456",
  "date": "2025-10-17T08:15:30.000Z",
  "event": "accountAdded",
  "data": {
    "account": "gmail-user456"
  }
}

Handling the Event​

The payload carries nothing but the account ID. Create the local record here, in a pending state, and let the events that follow move it on. Query Get Account if you need the name, address or account type.

async function handleAccountAdded(event, headers) {
  const { account, date } = event;
  const eventId = headers['x-ee-wh-event-id'];

  // Record the new account in a pending state. authenticationSuccess,
  // authenticationError or connectError will report the outcome
  await db.accounts.create({
    data: {
      emailEngineId: account,
      status: 'connecting',
      createdAt: new Date(date),
      lastEventId: eventId
    }
  });
}

Event Sequence​

When a new account is added and connects, you receive:

  1. accountAdded - Account is registered (this event)
  2. authenticationSuccess - The mail server or provider accepted the credentials
  3. accountInitialized - The account reached the connected state for the first time

For an IMAP account authenticationSuccess is sent as soon as the login succeeds and accountInitialized after the first pass over the folders. 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 accountInitialized first; do not depend on the order between the two if you support older releases.

If authentication fails:

  1. accountAdded - Account is registered (this event)
  2. authenticationError or connectError - The credentials were rejected, or the server could not be reached

Differences from Other Account Events​

EventWhen TriggeredWhat It Means
accountAddedImmediately after account creationAccount config is stored, connection not yet attempted
authenticationSuccessAfter successful authenticationAccount can connect to mail server
accountInitializedAfter the first successful syncMailboxes and messages are available
accountDeletedWhen account is removedAccount has been deleted from EmailEngine

See Also​