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}/aliasesreturns the mailbox's Send As aliases (the addresses besides its own) and tells you which ones you can send from.POST /v1/email/sendaccepts any sendable alias asfrom.emailwith the samemailer_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
| Mailer | Mailer id prefix | List aliases | Send from an alias |
|---|---|---|---|
Google / Gmail OAuth, send + read (config_type: smtp_imap) | oauth_smtp_imap_ | Supported | Supported |
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 IMAP | basic_… | Not supported (422) | Not supported |
| Verified sending domains | domain_… | Not applicable | Not applicable: send from any address on the verified domain |
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:
| Address | Sendable |
|---|---|
| The mailbox's own address | Yes, 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 address | No |
Prerequisites
- A Gmail OAuth mailer connected as send + read (
mailer_idstarts withoauth_smtp_imap_). See the OAuth Configuration Guide. - The alias added in Gmail under Settings → Accounts → Send mail as and verified by its owner.
- A valid API token (the same auth used for other
/v1endpoints).
List a mailer's aliases
| Method | Path | Purpose |
|---|---|---|
GET | /v1/oauth/{mailer_id}/aliases | List the addresses the mailer can send from |
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
refresh | boolean | false | Read 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 }
]
}
| Field | Description |
|---|---|
email (top level) | The mailer's own address. Always sendable, and not repeated in aliases |
syncedAt | When EDITH last read the list from Gmail (UTC, RFC 3339). Empty if it has never been read |
aliases[].email | A Send As alias of the mailbox. Each address appears once (letter case is ignored when de-duplicating) |
aliases[].displayName | The name set for that address in Gmail. EDITH does not apply it automatically; pass it as from.name if you want it |
aliases[].default | true for the address Gmail uses by default when composing |
aliases[].status | accepted (ready to use) or pending (waiting for the owner to confirm it) |
aliases[].sendable | true if POST /v1/email/send will accept this address as from.email |
Errors:
| Status | When | Error message |
|---|---|---|
| 400 | Missing mailer id | Invalid Mailer ID |
| 404 | The mailer does not exist in your account | mailer not found |
| 409 | The mailer is inactive | mailer is inactive |
| 422 | The mailer is not a Gmail send + read mailer | send as aliases are only available for Gmail mailers connected for both sending and reading |
| 422 | Gmail refused the stored credentials or read access | the mailer must be reconnected before its send as aliases can be read |
| 502 | Gmail could not be reached | could 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:
| When | Error 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 Gmail | from address is a send as alias that is still awaiting verification in Gmail |
| Gmail refused the stored credentials or read access | the mailer must be reconnected before its send as aliases can be read |
| Gmail could not be reached to check the alias | could not read the mailer's send as aliases from Gmail, please retry |
| The mailer is inactive | mailer 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 afterrefresh=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=truecall, returns the "could not read" error. - No automatic default: EDITH never chooses an alias.
fromis required on every send and is sent exactly as given once it passes the check.aliases[].defaultonly reports Gmail's own default; use it to preselect an alias in your UI. - Display name: the name recipients see is
from.namefrom 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 withrefresh=trueafterwards. - 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 defaultgappssmtp.comkey, 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 oneSMTP_ERRORevent with the reasonMicrosoft refused to send from this address: the connected mailbox does not have Send As permission for it (ErrorSendAsDenied). …, and the mailer stays active.