Skip to main content

Send As Aliases Guide

This guide covers sending from a Gmail mailbox's Send As aliases: the extra addresses the mailbox is allowed to send from, such as sales@acme.com on John's john@acme.com mailbox. You can list a mailer's aliases, then use one as from.email when sending.

Overview​

A connected mailer normally sends only from its own address. Gmail lets a mailbox owner add more addresses under Settings → Accounts → Send mail as. EDITH reads that list and can send from those addresses through the same mailer.

How it works:

  • GET /v1/oauth/{mailer_id}/aliases returns the mailbox's Send As aliases (the addresses besides its own) and tells you which ones you can send from.
  • POST /v1/email/send accepts any sendable alias as from.email with the same mailer_id. The email is sent through the mailbox, From shows the alias, and it appears in the mailbox's Sent folder.
  • EDITH keeps a copy of the alias list on the mailer and checks the from address against it before sending. An unknown or unverified address is rejected with a clear error instead of being sent.

What's supported​

MailerMailer id prefixList aliasesSend from an alias
Google / Gmail OAuth, send + read (config_type: smtp_imap)oauth_smtp_imap_SupportedSupported
Google / Gmail OAuth, send only (config_type: smtp)oauth_smtp_Not supported (422)Not supported
Google / Gmail OAuth, read only (config_type: imap)oauth_imap_Not supported (422)Not applicable (cannot send)
Microsoft / Outlook OAuth (any connection type)oauth_…Not supported (422)Not supported
Basic SMTP / basic IMAPbasic_…Not supported (422)Not supported
Verified sending domainsdomain_…Not applicableNot applicable: send from any address on the verified domain
Why send + read only

Reading the alias list needs Gmail read access (gmail.readonly), which only send + read connections have. Send-only mailers keep working exactly as before for their own address. To use aliases on a send-only mailer, connect the mailbox again as send + read (smtp_imap).

Which addresses are sendable:

AddressSendable
The mailbox's own addressYes, always (letter case does not matter)
An alias Gmail shows as verified (status: accepted)Yes
An alias still waiting for the owner to confirm it (status: pending)No, until it is verified in Gmail
Any other addressNo

Prerequisites​

  1. A Gmail OAuth mailer connected as send + read (mailer_id starts with oauth_smtp_imap_). See the OAuth Configuration Guide.
  2. The alias added in Gmail under Settings → Accounts → Send mail as and verified by its owner.
  3. A valid API token (the same auth used for other /v1 endpoints).

List a mailer's aliases​

MethodPathPurpose
GET/v1/oauth/{mailer_id}/aliasesList the addresses the mailer can send from

Query parameters:

ParameterTypeDefaultDescription
refreshbooleanfalseRead Gmail now instead of returning the stored list. Use it right after adding or verifying an alias.
curl "https://<your-host>/v1/oauth/{mailer_id}/aliases" \
-H "Authorization: Bearer <token>"

Response (200):

{
"success": true,
"mailerId": "oauth_smtp_imap_01JC3BBW8S9YGX2VNKG5MD7BTA",
"email": "john@acme.com",
"syncedAt": "2026-10-22T09:30:00Z",
"aliases": [
{ "email": "sales@acme.com", "displayName": "Acme Sales", "default": true, "status": "accepted", "sendable": true },
{ "email": "billing@acme.com", "displayName": "", "default": false, "status": "pending", "sendable": false }
]
}
FieldDescription
email (top level)The mailer's own address. Always sendable, and not repeated in aliases
syncedAtWhen EDITH last read the list from Gmail (UTC, RFC 3339). Empty if it has never been read
aliases[].emailA Send As alias of the mailbox. Each address appears once (letter case is ignored when de-duplicating)
aliases[].displayNameThe name set for that address in Gmail. EDITH does not apply it automatically; pass it as from.name if you want it
aliases[].defaulttrue for the address Gmail uses by default when composing
aliases[].statusaccepted (ready to use) or pending (waiting for the owner to confirm it)
aliases[].sendabletrue if POST /v1/email/send will accept this address as from.email

Errors:

StatusWhenError message
400Missing mailer idInvalid Mailer ID
404The mailer does not exist in your accountmailer not found
409The mailer is inactivemailer is inactive
422The mailer is not a Gmail send + read mailersend as aliases are only available for Gmail mailers connected for both sending and reading
422Gmail refused the stored credentials or read accessthe mailer must be reconnected before its send as aliases can be read
502Gmail could not be reachedcould not read the mailer's send as aliases from Gmail, please retry

Send from an alias​

No new request fields: put the alias in from.email and use the same mailer_id.

curl -X POST "https://<your-host>/v1/email/send" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "sales@acme.com", "name": "Acme Sales" },
"to": [{ "email": "customer@example.com" }],
"subject": "Your order",
"content": [{ "type": "text/plain", "value": "Thanks for your order." }],
"mailer_id": "oauth_smtp_imap_01JC3BBW8S9YGX2VNKG5MD7BTA",
"settings": {}
}'

Response (200): {"success": true, "ref_id": "01M5H0K15XBE0YFBEXPQYCGA57"}. Everything else about the request, webhooks and email logs is the same as a normal send. See the Email Sending Guide.

Errors (400) when the from address is not allowed:

WhenError message
The address is not one of the mailbox's aliases (or the mailer is not a Gmail send + read mailer)from address does not exist with the provided mailer_id (unchanged from before)
The alias exists but is still pending in Gmailfrom address is a send as alias that is still awaiting verification in Gmail
Gmail refused the stored credentials or read accessthe mailer must be reconnected before its send as aliases can be read
Gmail could not be reached to check the aliascould not read the mailer's send as aliases from Gmail, please retry
The mailer is inactivemailer is inactive for the provided mailer_id — please reauthorize the connection

Sends from the mailbox's own address never need the alias list, so they behave exactly as before. Sends from a known, verified alias are checked against the stored list and do not wait on Gmail.


Notes & limits​

  • When the list is read from Gmail: when the mailer connects or reconnects; when you call the list endpoint with refresh=true; when the stored copy is more than 24 hours old; and when a send uses an address that is not verified in the stored copy and the copy is more than 5 minutes old. A newly added or newly verified alias therefore works on the next send, or at once after refresh=true. There is no background polling.
  • Repeated unknown addresses: a burst of sends from an address that is not an alias reads Gmail at most once every 5 minutes per mailer; the other sends are rejected from the stored copy.
  • Removed aliases: an alias removed in Gmail can still be accepted until the stored copy is read again (at most 24 hours, or at once with refresh=true). Gmail may then send the email from the mailbox's own address instead.
  • When Gmail is unavailable: sends and list calls use the stored copy. Only a mailer whose list has never been read, or a refresh=true call, returns the "could not read" error.
  • No automatic default: EDITH never chooses an alias. from is required on every send and is sent exactly as given once it passes the check. aliases[].default only reports Gmail's own default; use it to preselect an alias in your UI.
  • Display name: the name recipients see is from.name from your request, not the name set in Gmail.
  • Google Workspace admin aliases are not sendable on their own: an "Alternate email address (email alias)" added by the Workspace admin only lets the mailbox receive mail at that address. It does not appear in the list (and cannot be used as from.email) until the mailbox owner also adds it in Gmail under Settings → Accounts → Send mail as. For an alias of the same Workspace account Gmail usually accepts it immediately; call the list endpoint with refresh=true afterwards.
  • Deliverability depends on the alias domain's DKIM: Gmail keeps the alias as the From address and adds no Sender: ("on behalf of") header, but the envelope sender (Return-Path) stays the mailbox's own address, so SPF never aligns with the alias domain. DMARC passes only when the alias domain has DKIM signing turned on in the same Google Workspace (Admin console → Apps → Google Workspace → Gmail → Authenticate email). Without it Google signs with its default gappssmtp.com key, DMARC fails, and recipients outside the organisation are likely to spam or quarantine the email.
  • Aliases are managed in Gmail: EDITH cannot add or verify aliases. The mailbox owner adds them under Settings → Accounts → Send mail as and confirms the verification email Gmail sends.
  • Microsoft / Outlook: aliases are not supported. If Microsoft rejects a send with ErrorSendAsDenied (the mailbox has no Send As right for the From address), EDITH does not retry it: you receive one SMTP_ERROR event with the reason Microsoft refused to send from this address: the connected mailbox does not have Send As permission for it (ErrorSendAsDenied). …, and the mailer stays active.