Connected accounts

What Connected Accounts does

Connected Accounts links Google Workspace mailboxes to your brand so MailStalk can send through the Gmail API (gmail.send scope).

This matters for Gmail-route recipients — subscribers whose addresses require the special Gmail sending path:
• @gmail.com and @googlemail.com
• Any domain that matches a connected Google Workspace account on this brand (e.g. if you connected you@company.com, recipients at @company.com also use the Gmail route)

Other recipients (Yahoo, Outlook, custom domains not on your Workspace) use your normal campaign SMTP, not Connected Accounts.

Personal @gmail.com accounts cannot be connected for bulk sending. Only Google Workspace addresses (you@yourcompany.com) are accepted.

How Gmail-route sending works (scheduled & send now)

When a campaign is prepared (scheduled.php / queue worker), MailStalk checks each recipient. For Gmail-route addresses it picks one sending mode for the whole brand using this priority — confirmed in gmail_sending_behavior.php:

1. WS — Google Workspace (Gmail API)
If at least one connected Workspace account exists → mail is sent via the Gmail API from a linked Workspace inbox (round-robin across accounts).

2. CD — Custom domain (SMTP)
If no Workspace is connected, but you have a verified + active sender domain in Setup domain → mail uses your brand SMTP credentials. The From address comes from your domain mailbox (typically the SMTP username on that domain).

3. OD — MailStalk default SMTP
If neither Workspace nor a verified active domain is available → mail uses MailStalk’s shared campaign SMTP (configured as SMTP_*_CAMPAIGN — shown in the app as Mailstalk default SMTP / tetonltd.com).

Summary:
• Workspace connected → Workspace Gmail API sends.
• No Workspace, but verified active domain → your domain email via SMTP.
• No Workspace and no verified active domain → MailStalk’s default domain via SMTP.

You do not pick the mode per email — the brand’s current setup decides automatically. The Connected Accounts page shows your active mode in the “Gmail-route sending mode for this brand” banner.

Why Google Workspace is recommended

Gmail and Google are sensitive to bulk mail and spam rate. Sending @gmail.com mail through generic shared SMTP (OD mode) can hurt inbox placement compared with authenticated Gmail API sends from your own Workspace mailbox.

Workspace mode (WS) sends through Google’s API with OAuth from an account you control — the path Google expects for automated sending at scale. MailStalk still respects per-account daily and hourly caps so you stay within safe limits.

Without Workspace you can still send Gmail-route mail using CD (your verified domain) or OD (MailStalk default domain), but Workspace is strongly recommended for the best deliverability to Gmail inboxes.

Connect Google Workspace

1. Open Connected Accounts from the sidebar.
2. Click Connect Google Workspace and sign in with a Workspace account (not @gmail.com).
3. Approve gmail.send and related OAuth permissions.
4. The account appears under Linked accounts with usage meters.
5. Connect more Workspace accounts to increase combined daily capacity.

Workspace daily and hourly limits

Each connected Workspace account has rolling quotas tracked by MailStalk (gmail_quota.php):

Paid Workspace (default):
• Daily: 2,000 emails per account per rolling 24-hour window
• Hourly: 40 emails per account per rolling 1-hour window

Trial Workspace (mark account as trial on Connected Accounts):
• Daily: 500 emails per rolling 24-hour window
• Hourly: 40 per rolling hour (same as paid)

How limits work:
• Windows are rolling from the first send in each window (not midnight reset).
• Before each send, MailStalk reserves one slot on an account with available quota (least recently used first).
• If hourly limit is hit, sending to Gmail-route recipients pauses until that account’s hour window resets (up to ~1 hour).
• If daily limit is hit, the account status becomes exhausted until the 24-hour window resets.
• Failed API sends can release the reserved slot; successful sends count toward both counters.
• Multiple Workspace accounts: quotas add up (e.g. two paid accounts ≈ 4,000/day combined).
• When all accounts are exhausted, Gmail-route sends defer and you may receive a quota notification email.

The Linked accounts table shows 24h usage (bar) and Hourly (sent/limit) per account. Brand monthly quota still applies on top of these Gmail limits.

Manage linked accounts

Linked accounts table columns:
• Email — connected Workspace address.
• Type — Workspace (or legacy personal Gmail if an old link exists — disconnect these).
• 24h usage — daily_sent / daily_limit with progress bar.
• Hourly — hourly_sent / hourly_limit.
• Status — active, exhausted, blocked, or revoked.

Actions:
• Mark trial / Mark paid — switches daily limit between 500 and 2000.
• Disconnect — revokes OAuth and removes the account from rotation.

Legacy personal @gmail.com connections are unsupported; disconnect and use Workspace instead.

Sending without Workspace

You are not required to connect Workspace, but Gmail-route recipients still need a valid mode:

Option A — Custom domain (CD): Verify and activate your domain under Setup domain. Ensure brand SMTP host, port, username, and password are set. Gmail-route mail sends from your domain mailbox via SMTP.

Option B — MailStalk default (OD): If you have no Workspace and no verified active domain, MailStalk’s default campaign SMTP is used (shared MailStalk sending domain).

Campaign preflight (before send) checks that Gmail-route recipients can be sent. If configuration is missing, send is blocked with an error pointing you to Connected Accounts or Setup domain.

Non-Gmail recipients always use your standard campaign SMTP path regardless of Connected Accounts.

Related topics