Help Desk

Connecting Email

The four ways to connect a support inbox (Gmail, Outlook, SMTP/IMAP and email forwarding), the full forwarding setup of DNS records, domain verification and inbox forwarding, doing it through Copilot or the API, and how a forwarded message is matched to an address.

Before the bot can answer email, Octocom needs two things: permission to send as your support address, and a way to receive what customers send to it.

There are four ways to arrange that, all under Settings → Channels → Email → New email address. Three of them connect to a mailbox by signing into it. The fourth, Email forwarding, doesn't need a mailbox to sign into at all.


Choosing how to connect

OptionYou needSetupReceiving
GmailA Google Workspace account for the addressOne Google loginPushed to us as mail arrives
OutlookA Microsoft 365 account for the addressOne Microsoft loginPushed to us as mail arrives
SMTP/IMAPHost, port, username and password for bothOne formPolled once a minute
Email forwardingDNS access for the domain, plus a forward ruleDNS records + forwardingForwarded from your real mailbox

Gmail and Outlook are the quickest options for a real mailbox you can sign into: a single OAuth login, no DNS changes, and mail reaches us the moment it lands rather than on a poll. If your support address has its own Google Workspace or Microsoft 365 mailbox and login, use these and skip the rest of this page. For a Google Workspace group without its own mailbox or login, choose Email forwarding instead.

SMTP/IMAP covers everything else with a real mailbox and a password behind it: Zoho, Fastmail, cPanel, a mail server you run. You give us the same credentials any mail client would use, and sending goes out through your provider's own server, so your existing SPF and DKIM keep working untouched.

Email forwarding is for an address with no account to sign into, or one you'd rather not send through:

  • A distribution list, Google Workspace group or alias with no mailbox and no password of its own.
  • A provider with no IMAP, or one whose security policy blocks app passwords.
  • Sending limits or deliverability on your own server that you don't want a support queue running through.

It's the only option that asks you to touch DNS, and in exchange the sending side stops depending on your mail provider entirely.

Only forwarding addresses show anything in the Setup column of the email table. Gmail, Outlook and SMTP/IMAP addresses are connected by login or credentials — they either work or they don't, and there's nothing to verify.


How email forwarding works

It is not a mailbox. Nothing is stored on our side, there's no webmail to log into, and your existing mail host doesn't change. It's two halves bolted onto an address you already own:

  • Sending — we register your domain with our sending infrastructure and you prove ownership through DNS. After that, replies from the bot and from your agents leave as support@yourdomain.com, signed with DKIM on your own domain.
  • Receiving — you forward your real inbox to a private relay address we issue you, ending in @relay.octocom.ai. Everything landing in your mailbox is copied to us and becomes a conversation.

Mail therefore keeps arriving in your original mailbox as well. Octocom never signs in and never deletes anything there. The two halves also fail independently: stop the forwarding rule and inbound support stops while sending carries on, which is the half-broken state the Setup panel exists to catch.


Which address a message is matched to

Forwarding hides a detail that matters as soon as you have more than one support address: the message we receive was addressed to your mailbox, not to us. We have to work out which of your configured addresses it belongs to, and the answer decides which address the reply goes out from.

What the message has to look like

Two headers do the work:

HeaderMust be
FromThe customer's own address, not your mailbox or your forwarder
ToThe address the customer wrote to

A plain forwarding rule preserves both, which is all we need. What breaks it is a rule that rewrites the sender, because then every conversation looks like it came from your own domain: forward-as-attachment, "resend as", and some mailing-list style rewrites all do this. If you have a choice of mechanism, pick the one your provider calls forwarding or redirect rather than one that re-sends the message as itself.

How we pick the address

In order, stopping at the first hit:

  1. To, matched exactly against the addresses you've configured.
  2. Cc, then Bcc, the same way — this catches customers who put your support address in copy.
  3. The relay address the forward delivered to, read from the Delivered-To and X-Forwarded-* headers your provider adds. Each relay address belongs to exactly one configured address, so this always resolves.

Step 3 is the one doing the work in most real setups, and it's why a funnel works.

Aliases, groups and funnels

You do not have to configure every alias your customers write to. If help@, trade@ and returns@ all funnel into support@, and support@ is the address you connected, everything arrives and becomes a conversation — step 3 matches on the relay address regardless of what the To header says.

What you get in exchange is a single identity:

The reply goes out from the configured address, not the address the customer originally wrote to. A customer who emails help@yourdomain.com through a funnel into support@yourdomain.com receives the answer from support@yourdomain.com, and replies to that thread from then on.

That is usually what people want from a funnel, but it is a decision, so make it deliberately:

  • Keep the funnel if one support identity is fine. Simplest to run: one address to connect, one forwarding rule, one sender to verify.
  • Connect each address separately if trade@ has to keep answering as trade@. Add each one under New email address, and give each its own forwarding rule. The domain is verified once and shared, so the extra work per address is small.

You can mix the two: connect the addresses whose identity matters, and let the rest funnel.

If a message matches none of the three steps — no configured address in To/Cc/Bcc, and no recognised relay address — it cannot be attributed to a business and is discarded rather than delivered somewhere arbitrary. Sending a test message through each forwarding path before you move production traffic is worth the five minutes.


Connecting an address

You'll need DNS access for the domain and access to the mailbox's forwarding settings. Budget about fifteen minutes, plus however long your DNS takes to propagate — minutes on most providers, occasionally hours.

First, select the intended business in the business selector at the top, then open Settings → Channels → Email. For an isolated test, select your test business before adding the test address.

1. Add the address

New email address → Email forwarding, type the full address (support@yourdomain.com), save. It appears in the table with a Set up sending badge. Open Setup on that row — the remaining three steps all happen in this one panel, which always shows you whichever is outstanding.

2. Publish the DNS records

Press Set up sending. Registering the domain takes up to a minute, after which the panel lists four records to add wherever you manage DNS:

TypePurpose
TXTProves you own the domain
TXTSPF — lets us send on your behalf
CNAMEDKIM — signs your outgoing mail
CNAMEDKIM2 — the second signing key, rotated alongside

Three things account for nearly every failed verification:

  • Never add a second SPF record. If the host already has a v=spf1 TXT, merge our include: into it. Two SPF records on one host is invalid and breaks SPF for all your mail, not just ours.
  • End SPF in -all, and keep it there. Azure rejects ~all. -all only rejects senders your record doesn't list, so make sure every service that sends as your domain is included rather than switching back to ~all later.
  • The DKIM CNAMEs must be DNS-only. On Cloudflare that's the grey cloud, not orange. A proxied record answers with an IP address instead of a CNAME and can never verify.
  • Watch the host. The verification TXT goes on the exact name shown, which may be a subdomain rather than the apex.

3. Verify the domain

Press Verify domain. Each record is checked separately and reported on its own line, because any subset can fail and "it didn't work" tells you nothing. Fix whatever failed and retry just that record — anything already verified stays verified. Where our own DNS lookup can explain a failure, the reason appears underneath it: two SPF records on one host, a proxied CNAME, a token that doesn't match the one we issued.

Once all four pass, the rest is automatic. The badge reads Finishing setup for a few seconds and needs nothing from you.

DNS changes take time to reach us. If a record looks correct in your DNS panel but won't verify, wait a few minutes and retry it rather than re-editing it — a second edit usually just resets the clock.

4. Forward your inbox

Sending now works, but nothing reaches you yet. The panel shows a forwarding address unique to this one address — copy it and create a forwarding rule for support@yourdomain.com at your mail provider.

For example, if your test address is a Google Workspace group called helpdesk-test@yourdomain.com, copy the relay address shown in Setup for that address on your test business and add it as a member of that group. Use the exact generated relay address. Adding it to the test group lets you test delivery without changing your live support group's members or routing.

Nearly every provider then sends a confirmation code or link to verify the destination. That confirmation goes to the relay rather than to a mailbox anyone reads, so we catch it and put it in front of you twice: in the Setup panel under Confirmation received, and in your inbox as a conversation that's already handed off, so the bot never answers it. Enter the code (or open the link) back at your provider, then press Mark as done.

The badge flips to Connected once real mail actually arrives at the relay — not when you finish the steps. That's deliberate: arriving mail is the only proof forwarding is genuinely live.

If forwarding was set up before Octocom issued you a relay address — an arrangement from an earlier manual setup — it keeps working. The address is recognised from the first ordinary email that arrives through it.


After it's connected

The Setup column stays on the row as a live status, not just a wizard you finish once:

BadgeMeaning
Set up sendingThe domain hasn't been registered yet.
Verify domainDNS records are waiting to be published or verified.
Finishing setupVerified; internal setup is completing. No action needed.
Confirm forwardingSending works. Nothing has arrived through the relay yet.
ConnectedSending and receiving are both working.
Sending unavailableWe couldn't check the sending side just now. Forwarding is unaffected.

More addresses on the same domain — add each one separately (support@, orders@, returns@). The domain only has to be verified once, so for the second and later addresses open Setup, press Verify domain to register the new sender, and go straight to forwarding. Do this for the addresses that need to answer under their own name; anything funnelling into an address you've already connected needs nothing, as matching explains.

Who owns the domain — it belongs to the organization that connected it. Sibling businesses under the same organization share it freely; a different Octocom account can't claim it. If you're told the domain is already connected elsewhere and you believe it's yours, contact support.


Setting it up through Copilot or the API

Forwarding inboxes can be connected end to end without opening the dashboard. Ask Copilot to connect support@yourdomain.com by email forwarding, or use the same operations directly:

StepMCP toolREST endpoint
Add the addresscreate_email_inboxPOST /rest/v1/email-inboxes
Read what is left to doget_email_inbox_setupGET /rest/v1/email-inboxes/{inboxId}/setup
Verify the domain's DNSverify_email_inbox_domainPOST /rest/v1/email-inboxes/{inboxId}/verify-domain

The setup read never changes anything. It returns the same state as the Setup panel and more: the four DNS records with Azure's status for each, and a live public DNS lookup per record showing the host queried, the expected value, the values found, which resolver answered and what is wrong. warnings lists records Azure verified that DNS no longer matches, such as an SPF record switched back to ~all. It also reports whether sending works, the relay address to forward to, whether forwarded mail has arrived, and any forwarding confirmation codes captured at the relay. Its nextAction field names the step that unblocks the inbox: publish_dns_records, verify_domain, set_up_forwarding, confirm_forwarding or retry_later.

Verifying is safe to repeat. It creates the sending domain if it is missing, checks each record, and finishes sending setup as soon as all four pass. Gmail, Outlook and SMTP/IMAP inboxes still connect in the dashboard, because they need a sign-in or credentials; for those, the setup read reports only whether they are connected.


Attachments

Agents can attach files of up to 100 MB to a reply: images, PDF, Word, Excel, PowerPoint, TXT, CSV, Markdown, video, audio (MP3, M4A, WAV) and ZIP archives. ZIP archives containing programs or scripts and Office files with macros are refused. Some recipients' mail filters still remove ZIP files, especially password-protected ones, so check with the customer if one doesn't arrive. For addresses connected through email forwarding, Gmail, Outlook or SMTP, Octocom keeps each email small enough for every provider and recipient mailbox to accept it:

  • Up to 5 MB of files in total are attached to the email as usual.
  • Larger files, largest documents first, are sent as download links in an Attachments list under the message, above the signature. Customers open them without signing in: the link opens a page that starts the download straight away. Some email apps, such as Proton Mail, block downloads from links; there the page explains how to get the file (reload the page or open the link in the browser).
  • Large photos and screenshots are resized for the email instead of becoming links. The original stays in the conversation.

Nothing changes in the composer: attach files as usual and Octocom decides how each one is delivered when the email is sent. If an email fails to send and is retried, the retry carries the same attachments, formatting and signature.


Troubleshooting

Verification passes but no customer email appears. The forwarding rule is missing, unconfirmed, or pointed at the wrong address — the Setup panel will still read Confirm forwarding.

The confirmation never appears in Octocom. Some providers send it to the mailbox owner instead of the destination, so check the original inbox first, spam included. If it's nowhere, contact support — the message may have arrived without enough information to match it to your address.

Email goes out from the wrong address. Replies leave on the configured address the conversation was matched to, which is not necessarily the address the customer typed — see Which address a message is matched to. Anything with no thread behind it — outbound mail the bot initiates — uses the business's primary address instead. Use Set as Primary on the row you want those to come from.

Everything worked, then outbound stopped. Check the SPF and DKIM records are still present and that SPF still ends in -all. DNS migrations and registrar transfers routinely drop them.

"Gmail disconnected" banner. Google has stopped sharing the mailbox with Octocom — usually because the account's password changed, a Workspace admin revoked third-party access, or the login was removed. Until it's reconnected, mail to that address isn't reaching the Help Desk and replies can't be sent; nothing else is affected, and no settings are lost. Press Reconnect on the banner (or open the address in Settings → Email) and sign in to Google as that mailbox. If you can't sign in to it yourself, use Send link to mailbox owner: the link arrives from Octocom's own address, works once, expires in 7 days, only accepts a Google sign-in for that exact mailbox, and needs no Octocom account. Once it's back, the row reads Active again and the banner clears on its own.


  • Email Signatures — automatically add a shared signature to emails sent by agents or the bot.
  • Email Rules — route inbound mail by sender, domain or subject before the bot sees it.
  • Email Conversation Merging — how replies are threaded into existing conversations.

Email response delay

Each connected address has its own Email response delay (minutes) under Edit settings. Set it to zero for no configured wait. Changing one address's response delay does not change the delay for other addresses in the business.

If the customer writes again while the AI is still writing its reply, the AI finishes that reply and then answers the new message, as if it had arrived just after the reply. It never abandons a reply partway, since the reply may already have taken an action such as a cancellation.

Sender identity is managed by the connected email provider. Octocom does not provide a sender-name override.

On this page