Send As Addresses via API and MCP

TrekMail separates two jobs that use different credentials and permissions:

1. The Dashboard/Ops surface owns reusable SMTP profiles and domain routing. It uses a tm_live_ token with smtp:read or smtp:write.
2. The Webmail/Message surface owns the From addresses available to one mailbox and one connected inbox. It uses a tm_msg_ token with messages:read, messages:write, or messages:send.

This is deliberate. A mailbox token can select an already-authorized sending route, but it cannot reveal SMTP credentials or manage another account's infrastructure.

The short version

• If you send with only external_account_id, recipients see that connected account's own address and its own SMTP server is used.
• If you also send a source-bound identity_id, recipients see the identity's business address. TrekMail uses the domain route or saved SMTP profile assigned to that identity, then saves the Sent copy in the connected inbox.
• Starter can configure and use this in webmail. Pro and Agency can also automate it through API or MCP. Nano has no connected-account slots.

The current catalog contains 244 REST API routes and 235 stdio MCP tools: 173 operations tools and 62 message tools. Hosted HTTP MCP exposes at most 234 tools because drive_file_upload accepts a local path and is intentionally not available on a remote server. Send As uses the existing SMTP and message families; a scoped connection sees only the relevant subset.

The routing model

When external_account_id is sent without identity_id, TrekMail sends through that external account's own SMTP server and uses its own address.

When both values are sent, TrekMail treats the external account as the inbox/Sent destination and the identity as the visible From + SMTP route:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

The identity and external account must be bound to each other. Omitting the source or supplying an identity from another mailbox returns 422 identity_unavailable.

1. Inspect or configure SMTP in the Dashboard API

Use an Ops token.

Profile reads never return the password. The usage endpoint is the safe way for an agent to explain the impact before editing or deleting a shared profile.

MCP tools: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. List addresses for the exact inbox

Use a Message token:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

The response includes source-specific identities, all configured external_identities, sending_addresses, eligible send_as_domains, the mailbox reply_from_policy, and (only for the account-owner mailbox) saved smtp_profiles that may be selected directly.

MCP: call list_identities with external_account_id.

Hosted MCP versus local stdio

Message tools have one important transport difference:

• Hosted HTTP MCP (OAuth): also pass mailbox_id on every message tool call. The hosted server uses it to provision a short-lived message token for that exact mailbox. For example, call list_identities with { "mailbox_id": 7, "external_account_id": 42 }.
• Self-hosted stdio MCP (tm_msg_): do not pass mailbox_id. The static message token is already bound to one mailbox, so the tool schema only needs external_account_id.

external_account_id never replaces mailbox_id: it selects a connected inbox inside the already-authorized mailbox. Dashboard SMTP tools remain account-scoped and do not take mailbox_id in either transport.

3. Create a connected-inbox Send As identity

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email must already be this mailbox's primary address or an active send-enabled alias. Its domain must be active and owned by the same account. smtp_mode: domain follows the domain route configured in the Dashboard. smtp_mode: profile pins the identity to smtp_connection_id; direct profile selection is limited to the account-owner mailbox.

MCP: create_identity with kind=send_as. On hosted MCP, include the parent mailbox_id as described above.

4. Send, draft, schedule, reply, or forward

The ordinary message operations accept the same source pair:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id is supported by immediate send, draft save/update, and scheduled send. Reply/forward preparation accepts external_account_id and selects the matching identity from delivery headers. The selected identity is re-authorized when a queued message actually runs; disabling its alias, domain, profile, or connected account stops delivery rather than silently falling back to another From address.

MCP tools: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all, and prepare_forward.

Reply policy

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient replies from the address that received the message when possible. default always starts from the mailbox default for normal mailbox mail. MCP uses set_reply_from_policy.

Safety and isolation rules

• SMTP credentials never cross into the Message API or MCP response.
• Every external account and identity is constrained to the message token's mailbox.
• A connected Send As identity is usable only with its exact external_account_id.
• The From address must already be authorized as a mailbox address or send-enabled alias; the API cannot invent arbitrary From addresses.
• A working route is required before creation and checked again at delivery time.
• Custom Reply-To headers cannot conflict with an identity's saved Reply-To.
• MCP identity/profile mutations require TREKMAIL_ALLOW_DESTRUCTIVE=true; real delivery additionally requires TREKMAIL_ALLOW_SENDING=true and confirm_send=true.

No new token scope strings are required. Existing smtp:* and messages:* tokens continue to work according to their current permissions.

Which sending limit applies?

API calls also keep their own abuse safeguards: by default 60 send requests per minute per message token and 100 API sends per day across the mailbox. These apply regardless of which server ultimately delivers the email.