Owners and access
Every connection has an Owner, the person who connected it, and an Access level:- Personal. Only you, its owner, use and manage it.
- Shared with your brand. Everyone on the brand who can do the connection’s work uses it.
- Shared with your workspace. Every brand of the workspace can use it. Search Console, Google Analytics, Cloudflare, Slack and HubSpot can be shared this way. Mailboxes and WordPress belong to one brand.
Several connections to one provider
A brand can hold several connections to one provider, such as two Gmail mailboxes, Gmail beside Microsoft 365, or two Search Console accounts. Each is its own row. Every mailbox sends: each task picks the one it sends from. See the conversation’s sender. For data and site work, your brand reads from one connection at a time, and that row carries In use. Adding another keeps the one in use. Cloudflare takes crawler visits over from WordPress, and WordPress still applies site fixes. The ⋯ menu’s Use for item, which names your brand, moves your brand to that connection. The other one stays connected, and its row reads Working once its check passes. When the one in use is removed, nothing replaces it: the others read Setting up with Choose which connection to use, and Fix opens the pane at its Use for button. An account your brand already has is refused, including one the workspace shares with it. The dialog names it with its owner and access, such as “vlad@heralded.ai is already connected by Vlad Bisceanu (Personal)”. Its main button, such as Ask Vlad to share it, opens an email to the owner, and Use another Google account signs in again. When the workspace already shares the account with your brand, the dialog says Already available and its main button opens that connection. The same mailbox on another brand is allowed and shares its daily allowance.The table
The table groups connections under Connected and Available. Each row shows the connection, its account, who can use it on the line under the account, such as “Personal · Vlad Bisceanu” or “Shared”, its status and Last activity. Needs you rows come first and are highlighted. A provider you have connected keeps its Available row with Connect another. A mailbox’s reads Another mailbox to send from. HubSpot has a Plus label. Providers coming soon appear in one line below the table.- Working shows the latest activity or connection check.
- Setting up says what it waits for. First read names your next weekly report, or your first report before you finish onboarding. A mailbox waits for its first sync.
- Needs you names the problem or choice owed. A sitemap problem shows the report’s date. Lost access shows when the connection last worked, when that date is known.
- Not connected offers Connect, or See plans when your plan does not include the provider.
Connecting
Connect opens the provider’s dialog, such as Connect WordPress, with Access, Choose and Done at the top. Access lists what Heralded reads and does, then asks Who can use it: Only me, Everyone on your brand, and Everyone in your workspace where the provider allows it, the workspace has more than one brand and you manage the workspace. The default comes first. A member who can send emails but not change settings connects only a mailbox of their own. A member who can change settings but not send emails connects a mailbox only for the brand. Continue to the provider’s sign-in screen. After authorizing, Choose opens only when a property, zone, portal, channel or Gmail sending address needs your choice. Property choices include only sites that serve your brand, with exact matches first. Search Console shows Domain or URL prefix and your access level. Select Done to open the connection’s pane with a confirmation. Closing a choice keeps the account connected, and the pane’s picker makes the choice still owed. WordPress and Sitemap use fields in Access without a separate sign-in screen.The connection’s pane
Select a row to open its pane. Every connection’s pane has the same parts, in this order:- Header. The provider, the connection’s name, and its status with the same activity, wait or problem as the table.
- Properties. Owner and Access first, then Account, the provider’s own settings, Used by for a workspace connection, and Connected with who connected it and when. A setting you can change is its own control: pick another property, zone or channel from its picker, or type the sitemap’s address. A problem with one setting shows in red under it. A mailbox shows Send as, Sending hours, Time zone and Daily limit with what it sent today. The addresses a mailbox sends as, their signatures and its From tests show only to people who may send from it. Everyone else sees its account, owner, access and status. WordPress shows its Plugin version and links Site fixes to Automation. Slack shows its Weekly report switch, and HubSpot its customers and attribution.
- Notice. Only when the connection isn’t working: what it waits for, or what broke.
- Activity. Up to five dated events, newest first, with who did each, such as “Shared with heralded.ai by Vlad Bisceanu”, and a link to the page where the data shows.
- Earlier accounts, when there are any.
- Footer. Ask the Herald, Check connection, and Reconnect or Connect when one is due.
Connection references in the API
Each connection also carriesstatus_fact and activity in /v1/brands/{id}/settings and the assistant’s get_settings tool. status_fact has kind, reason, target, at and on. Its kind is activity, waits_for or problem, and it is null when not connected. For activity, reason names the activity kind. For problems, it names the problem code. A wait’s target is first_read, first_sync, choice or selection; on holds the next weekly report when known. at holds the event’s true date when stored. activity lists up to five dated events, newest first, as kind, at and label. First occurrences are labelled as firsts.
Each brand connection row carries binding_id, including in /v1/brands/{id}/settings and the assistant’s get_settings tool. Match it to subject.binding_id in the work read to find that connection’s operations. The value is null for mail, a sitemap or when no connection is selected. Brands using the same authorized account have separate binding IDs.
Google Search Console
Reads your search performance from one verified Search Console property. Unlocks. Search clicks on each page that serves a topic, in the topic pane, and in each page’s stats. The searches that bring people to your site become suggested topics. Access. Reads queries, pages, clicks, impressions and position for the property your brand uses, over 28 days. It writes nothing. The access is read-only. Before you connect. You need owner, full user or restricted user access to a verified Search Console property that covers your domain. Steps.- Press Connect and sign in to Google with an account that has the property.
- Allow read-only access to Search Console.
- If several properties cover your domain, select one and select Done.
Google Analytics
Reads the visits AI assistants send to your site from one Google Analytics property. Until Google approves Heralded’s access to Analytics, it is listed under Coming soon. Unlocks. Visits from AI on each topic in Topics and in each page’s pane, beside its citations. For an ecommerce brand, revenue from AI by assistant, landing page and product. Access. Reads sessions by landing page and source for the property your brand uses, over 28 days. For an ecommerce brand it also reads purchase revenue, orders and key events by landing page and source, item revenue by source, and your site’s own totals. It writes nothing. The access is read-only. Before you connect. You need Viewer access to the Google Analytics property that records your domain. Steps.- Press Connect and sign in to Google with an account that has the property.
- Allow read-only access to Analytics.
- If several properties record your domain, select one and select Done.
ai-assistant channel. For an unlisted source in that channel, Heralded names the source by its host. The count is a floor, because many AI apps strip the referrer and their visits count as direct. Only visits to your brand’s own domain and its www. address are counted. If the report includes another host, Heralded withholds its counts because Google Analytics does not identify which host a session landed on.
Revenue from AI counts a purchase for an assistant when the session that bought came from it. Google Analytics credits a direct return visit to the source before it, so a visitor who came back on their own still counts for the assistant that sent them. Revenue is a minimum for the same reason visits are, and AI Overviews and AI Mode cannot be told apart from other Google traffic. A property that recorded no purchase in the 28 days shows no revenue rather than zero. Conversion rate needs sessions, so a product has revenue and units bought but no conversion rate. If your property cannot split item revenue by source, products show no revenue.
After removal. Heralded’s access is revoked and pulling stops. Visits from AI leave Content, and past weekly reports keep their numbers.
Cloudflare
Counts crawler requests through Cloudflare, including cached pages and requests blocked before they reach your site. It reads zone analytics and writes nothing. See Connect Cloudflare for setup, the first pull, daily updates, verification and disconnecting.Sitemap
Finds your site’s pages from its sitemap. It is a public file, so it needs no authorization. Unlocks. Pages missing from the sitemap, a finding on Website. Access. Reads your public sitemap, and robots.txt to find it. Writes nothing. When data arrives. Once Heralded finds a usable sitemap, it reuses the results for seven days. Reports inside that window use the saved check, page addresses and modification dates. Category and tag sitemaps are read again when finding generated archives. Each weekly report combines the sitemaps your robots.txt declares and follows nested indexes to build a page inventory, up to 50 files and 25,000 recorded addresses. Each file can contain up to 50,000 entries and 50 MB of uncompressed XML. Gzip-compressed sitemaps are supported. It records each address’s last modification date when the sitemap supplies one, and counts further addresses as unrecorded. It tries/sitemap.xml only when robots.txt declares none. The sitemap check evaluates every declared file and up to ten direct child files. An index is usable only when a child sitemap supplies pages. If that check reaches a file or size limit before it can tell, the sitemap stays unmeasured.
Open the Sitemap row to edit its Sitemap URL in the pane. The field contains your saved address. Without one, it stays empty and shows the discovered sitemap as a placeholder. Type an address and press Enter, or clear the field and press Enter to remove the fallback URL. An address you haven’t saved stays in the field when you close the pane, until you select Discard. Heralded checks the file before saving. An address that cannot be read as a sitemap stays in the field with its reason. The next weekly report tries the saved address only if discovery still finds nothing. Saving does not change the last report’s findings. Viewers see the address without the field.
WordPress
Lets Heralded apply site fixes and count AI crawler visits, through the Heralded Connector plugin. Unlocks. Fixes from Actions: robots.txt rules for AI crawlers and your homepage’s structured data, applied and read back to check they landed. Automation sets what Heralded may do without asking. Crawler visits show as AI crawlers in each page’s stats. Access. Writes only the robots.txt rules Heralded owns, and JSON-LD on posts and the homepage. Reads site health, the WordPress, PHP and plugin versions, and crawler counts. The connection pane’s Plugin version shows the installed plugin version from the last health check. Before you connect. You need WordPress admin access, an https site, WordPress 6.9 or later and PHP 8.1 or later. Steps.- Open Connect on the WordPress row. In Access, download the plugin, then install and activate it in WordPress under Plugins › Add New › Upload Plugin.
- Open Settings › Heralded Connector in WordPress and generate a token.
- Enter your site address and token in the same dialog, then select Connect. Once it succeeds, the connection’s pane opens.
- Crawl counts are a floor. The plugin counts a request only when WordPress runs it. A page cache or CDN that answers a crawler first hides that request from the plugin.
- A static robots.txt file wins. A robots.txt file on the server overrides the plugin’s rules.
- A fix has no revert. Heralded can’t take back a fix it applied. To undo one, change it in WordPress.
Microsoft 365
Sends the outreach emails you approve from your brand’s Microsoft 365 mailbox. Unlocks. Approve and send on emails with a source. An approved email goes from this mailbox in its working hours, with Undo until it leaves. Access. Sends only the emails you approve. Confirms each email went, notices bounces and syncs replies every ten minutes. It reads threads Heralded started and new mail from addresses you wrote to after the first send. Other message text is not stored. An AI reads each reply to sum it up and draft your answer. Attachments are listed by name and size; open them in your own mail. Heralded needs both: a grant without reading isn’t a connection. Before you connect. You need a Microsoft 365 work or school mailbox. To send from a shared mailbox, you need permission to send as it. Steps.- Open Connect on the Microsoft 365 row. To send from a shared mailbox, enter its address.
- Sign in to Microsoft and allow Heralded to send and read mail.
- 20 emails a day. A mailbox sends at most 20 emails a calendar day across every brand that sends from it. Its allowance uses the time zone recorded when the mailbox was first connected. Changing one connection’s sending hours does not reset it. An email past the limit goes on the next working day, and its task says so.
- 14 days between brands. A first email to an address another Heralded brand wrote to first waits until 14 days after that brand’s, and its task shows only the date it goes.
Gmail
Sends the outreach emails you approve from your brand’s Gmail or Google Workspace mailbox. It works as Microsoft 365 does, for approving, sending hours, limits, bounces and a lost connection. It isn’t available yet. Until Google approves Heralded’s access to Gmail, the Connections page doesn’t list it. Access. Sends only the emails you approve, and reads the mailbox to confirm each email went, to notice bounces and to read replies to the emails Heralded sent. An AI reads each reply to sum it up and draft your answer. Attachments are listed by name and size and never downloaded. Heralded needs both sending and reading: a grant without reading isn’t a connection. The mailbox is the one you sign in with. Gmail has no shared mailbox to name. Send as. The picker lists your mailbox and every alias Gmail holds. Addresses whose From test passed show Verified. Refresh addresses updates the list, and Add an address in Gmail ↗ opens Gmail’s settings. An address awaiting Gmail’s ownership check stays listed with Verify in Gmail and cannot send emails. Verify it in Gmail, then choose Refresh addresses. From on a task offers your mailbox’s own address and the addresses whose From test passed, and an email goes only from one of them. Choosing a verified address changes your sending address at once, with Undo. Your mailbox’s own address is always available. Choosing another address runs its test in the row, through Test sent, Arrived and signed, and Ready to send. Your current address keeps sending until the test passes. A pass applies the new address and offers Undo. Activity records when the address verified. If the test fails, the row shows the reason and Try again. After five minutes without a copy, it says The test never arrived. A late copy can still verify that test. Choosing another address cancels the earlier test. Reconnecting the same mailbox keeps its verified addresses and cancels its pending test. A different mailbox starts without those verifications. All aliases and connections to the same mailbox share its 20-email daily limit. A removed alias stops a waiting email for approval again. A failed alias check retries. Set the brand signature and copy your Heralded address in Brand settings → General → Emails. If your signature is empty, Use Gmail signature puts Gmail’s suggestion into the field. Choose Save to use it. After removal. Nothing more is sent. Google can end Heralded’s access to a Google account only all at once, for Gmail, Search Console and Analytics together. So Heralded asks Google to end it when the last of those connections for that account goes. While Search Console or Analytics still uses the account, they stay connected and Heralded’s access to your mailbox stays listed at myaccount.google.com/permissions, where you can remove it. That ends them too. Tick Also delete stored emails in the Disconnect question to also delete what the emails sent and received through the mailbox said.Slack
Posts each weekly report’s headline and what moved to one channel per brand. Unlocks. Your weekly report in the channel your team reads. Access. Writes messages to the channel each brand picks. Reads channel names, public and private, so you can pick one. It reads no messages. Before you connect. You need permission to install apps in the Slack workspace. For a private channel, invite @Heralded to it first. Steps.- Press Connect and sign in to the Slack workspace.
- Allow Heralded to post and to list channels.
- Select the channel this brand’s reports go to, then select Done. For a private channel, invite @Heralded first.
When a connection fails
If you cancel on the provider’s screen, or connecting fails there, Heralded reopens the dialog on the page you started from with the reason. Use Continue with Google, Continue with Slack or the provider’s own sign-in button to try again. A failed attempt creates no connection. Check connection in a connection’s pane asks the provider whether the connection still works. It doesn’t read new data. When a WordPress site fails, at connect or at a later check, Heralded names the cause and its fix: the plugin isn’t installed or active, the site redirected to another address, the site refused the token, the plugin is out of date, the site answered with a server error, Heralded couldn’t reach the site, or the site’s HTTPS certificate was refused.HubSpot
Reads this brand’s customers to identify promoters and classify how new contacts heard about you. HubSpot is on Plus. Until Heralded’s HubSpot app is configured, it appears under Coming soon for Plus brands. Access. Reads contacts, associated companies and deals, and NPS survey submissions. The authorization also requests contact write access. The sync makes no CRM changes. Before you connect. You need Plus and permission to install an app in your HubSpot portal. Authorize once for the workspace, or connect a brand’s own account. For a workspace-owned HubSpot connection, you need workspace settings permission to choose or change a brand’s customer partition. If you manage only that brand, you can use its approved partition and edit the promoter or attribution settings, or connect the brand’s own HubSpot account. Steps.- Press Connect and authorize Heralded in HubSpot.
- On the brand’s Connections page, choose the portal and answer Which customers are this brand’s? Choose associated company domains, a deal pipeline ID, or a contact property equal to a value. All customers is allowed only while one brand uses the portal. Every brand sharing a portal needs an explicit partition.
- Answer Where do promoters come from? The default is NPS survey submissions with a minimum score of 9. You can instead choose a numeric contact property and a minimum score. A promoter’s latest score must meet the rule and have been recorded in the last 12 months.
- Optionally name the contact property for How did you hear about us? Use HubSpot’s internal property names, then select Done.
attribution with the month, total classified contacts and counts by voice and named platform. Without an attribution property, or without Plus, attribution is null.
Limits. Each brand has 30,000 CRM API calls and 5,000 attribution classifications per UTC calendar month. Syncs read modified records in pages of 100 and save their progress. When a budget is reached, Actions shows HubSpot sync paused until the first of the next month.
After removal. The sync stops and this brand’s stored contact classifications are removed. Removing a workspace authorization revokes the grant for every brand using it. Changing the partition, promoter rule or attribution property starts a fresh sync for that binding.
AI assistants
Read your Heralded data from Claude, ChatGPT, Cursor, VS Code, Claude Code or any MCP client. Each member connects their own assistant by signing in from the assistant, and Your account › AI assistants lists the connected assistants for the workspace you are in. Owners and admins see every member’s assistants, each with connected by and the member’s name or email. See Connect an AI assistant.Coming later
Bing Webmaster, GitHub, Webflow, Shopify and Zapier are listed under Coming soon. They aren’t available yet. They have no connection button.API connection instances
Brand settings and MCPget_settings include an instances list for each provider. Each instance has its ID, account, owner, access, status, binding ID and in_use. The owner is named by their name, or by their address where they set none. Access is personal, shared_brand or shared_workspace. Mail instances always have in_use: false.
The provider’s existing fields remain. Its state is the most urgent of reauthorise, reconnect_required, degraded, needs_property and connected. Its binding_id names the selected binding, or is null when none is selected. For mail it is always null. While the state is reauthorise, reconnect_account_id is the instance the brand’s previous site held, which a reconnect for the new site names; it is null otherwise. A mail provider reports the newest last_activity, the most urgent instance’s status_fact, the five newest activity events and the total waiting_emails; its detail is empty.