One tracked email, end to end

Connect a mailbox (this is the BYOK step)

Open Settings → Integrations. Add an integration of type email — either a plain IMAP/SMTP mailbox (host, port, username, password) or an OAuth mailbox. The credential is written into your workspace Vault; Postgres keeps only the metadata row (provider, active flag, the Vault path, and when it was last tested). Nothing about your password is stored in the database.

• ▸The integration list is exactly what the org has connected — the same rows GET /api/v1/salesshift/settings/integrations returns, grouped by type: email, AI, payment.
• ▸Use the per-integration Test action after saving. It reads the credential back out of Vault and uses it against the provider for real. A Vault round-trip on its own proves nothing about whether the host, port or password still work.

Check the email worker before you send anything

Outbound mail does not go out from the control plane — it goes through a Go worker running on your tenant node, the same node vxcli node current reports. Confirm it is up and which providers it has: the health endpoint reports status, the provider list, whether Redis is connected, and the per-domain rate limit in messages per minute.

# The one SalesShift call that does not carry a credential — it is a
# plain GET against your own node.
vxcli salesshift worker health

# Node             https://node1.vxcloud.io
# Status           healthy
# Providers        [smtp]
# Redis            true
# Domain rate/min  20

Understand what you are allowed to send to

SalesShift has three kinds of person record and only one of them is mailable. A pool person is a row in the global prospect pool. Their address comes back masked — j•••@acme.com — until your organization spends a metered reveal on it. A saved lead is a snapshot of a pool person copied into your org. Still not mailable. A contact is a CRM record. Converting a lead is what creates one, and conversion is where consent metadata is written. Only a contact address goes into a send.

• ▸has_email tells you an address exists. email_revealed tells you whether you may see it. They are different questions.
• ▸The Python and Go bindings refuse a masked address on the send path outright, rather than let it reach a real domain. Do the same in your own scripts.

Create or pick a contact

Open Contacts. Either create one directly, or convert a lead: from Leads → Pool, open a person, reveal them (this spends one from your metered allowance), then convert. Conversion is idempotent — a lead that already has a contact reports the existing contact id rather than creating a second one.

Send the email

From the contact record, compose and send. The send goes through the same engine sequences use, in this order: suppression gate → per-mailbox daily cap and warmup ramp → the tenant node worker → tracking pixel and click rewriting → the event stream. A suppressed or unsubscribed recipient is rejected, and that gate is not optional.

• ▸Merge tags such as {{first_name}} resolve against the contact record, in both the subject and the body.
• ▸The response names the provider that actually carried the message — node-smtp, smtp, sendgrid, mailgun, platform or sink — plus a tracking id.

Read the engagement back

Two places show what happened. The email list shows every tracked outbound message with its status, open count and click count. The Conversations view shows the full thread with one contact — every tracked send plus any captured reply. Reply detection runs an IMAP pass roughly every five minutes, so a reply takes a few minutes to appear.

Confirm at the org level

The dashboard counters roll everything up: contacts, companies, open deals, active sequences, and the email funnel — sent, delivered, opened, replied, bounced. It is the fastest way to confirm your first send actually registered.