Build Now

Send Email on Behalf of User API

Email API

What Does "Send on Behalf" Mean in Email API?

Sending email on behalf of a user means your application dispatches messages directly from the user's own mailbox, not from a shared transactional sender. The recipient sees the user's real email address in the "From" field. This is the foundation of any SaaS product that handles email for its users.

What you will learn

How OAuth 2.0 grants send permission
Gmail, Outlook, and IMAP support
On-behalf vs transactional email APIs
Sending via the Unipile unified API
CRM, AI assistant, and support use cases
Legal compliance and user permissions
Try the Unipile Email API Read the docs
Sent from user's mailbox Real "From" address
Unipile Email API
Send on Behalf POST
POST /api/v1/emails
200 OK
GET /api/v1/emails/{id}
200 OK
GET /api/v1/accounts/{id}
200 OK
JSON payload
{ "account_id": "user_abc123", "to": [{ "identifier": "prospect@acme.com" }], "subject": "Following up", "body": "Hi Sarah..." }
OAuth 2.0 secured User grants permission
Building an email integration?

Read our Complete Email API Guide - OAuth flows, sync, send, and provider comparison.

Why SaaS Products Need On-Behalf Email Sending

Most SaaS products that touch email eventually face the same requirement: the user wants messages to come from their own address, not from a generic platform domain. Whether it is a CRM, an AI writing assistant, or a support tool, the moment your product sends emails for users, you need on-behalf sending. Here is why it matters - and how the three main use cases map to the API.

CRM Use Case

Sales reps send from their real Gmail or Outlook

In a CRM context, the salesperson is the one building the relationship. If your platform sends follow-ups from noreply@yourcrm.com, deliverability drops and the prospect is confused. With on-behalf sending, your CRM calls the Unipile API using the salesperson's linked account. Every email lands in the prospect's inbox showing the rep's real address.

Email threads stay in the rep's sent folder, keeping history in one place
Replies land in the rep's inbox for natural conversation continuity
Sender reputation is tied to the rep's domain, not a shared platform domain
AI Assistant Use Case

AI drafts and sends from the user's mailbox

AI email assistants - whether they auto-draft replies, schedule follow-ups, or summarize threads - need write access to the user's mailbox. Without on-behalf sending, the AI can only suggest; it cannot execute. With a linked account via the Unipile API, your assistant can send the approved message directly from the user's Gmail or Outlook with a single API call.

Draft approved: one API call dispatches it from the user's actual address
Works whether the user runs Gmail, Outlook, or any IMAP provider
Supports threading via reply_to parameter to keep conversations intact
Support Tool Use Case

Support agents reply from a shared support inbox

Customer support platforms often route tickets through a shared inbox like support@company.com. That inbox is itself a mailbox - it needs to be linked as an account. With Unipile, your platform can connect that shared Outlook or IMAP mailbox, letting any agent send replies that appear to come directly from the official support address, with full thread context preserved.

Shared inbox linked once, accessible to all authorized agents
Responses always show the correct company domain in the From field
Attachments, CC, and BCC all supported via the same unified endpoint
Better deliverability
Emails sent from the user's own domain pass SPF and DKIM checks tied to their account, not a shared sender.
OAuth-secured access
Users grant permission via their provider's OAuth flow. No passwords stored, fully revocable at any time.
One unified API
The same POST /api/v1/emails endpoint handles Gmail, Outlook, and IMAP accounts.
Faster time to market
Skip building separate integrations for Gmail, Outlook, and IMAP. Unipile normalizes all three behind one interface.
The key insight: your users already have email addresses their contacts trust. On-behalf sending lets your SaaS leverage that trust without asking anyone to switch providers or create a new inbox. For a broader picture of how email APIs work, see the Email API guide.
Start building for free

How On-Behalf Email API Works (OAuth 2.0 Flow)

Sending email on behalf of a user requires three things: the user's consent, a valid access token, and a send call through the provider's infrastructure. Here is how that flow works in practice, and how Unipile abstracts it into a single unified API. For a broader technical reference on sending endpoints, parameters, and provider differences, see our complete send email API guide.

1

User grants OAuth permission

The user clicks "Connect your email" inside your SaaS product. Unipile redirects them to their provider's OAuth consent screen - Google for Gmail users, Microsoft for Outlook and Microsoft 365 users. The user logs in and approves the requested scopes, which include the ability to send email on their behalf. No password is ever shared with your application.

For IMAP providers, the user enters their app-specific password or IMAP credentials directly in a Unipile-hosted form. Unipile stores the credentials encrypted and manages reconnection automatically.
2

Your app receives a linked account ID

Once the user completes the OAuth flow, Unipile stores the access token securely and returns an account_id to your application. This is a stable identifier for the user's linked mailbox. You store this ID in your database against the user record. All subsequent email operations for this user reference this account_id - you never touch the raw OAuth token.

Unipile handles token refresh automatically. If a Gmail or Outlook token expires, Unipile renews it in the background so your send calls never fail due to expired credentials.
3

Send via the provider's infrastructure

When your application needs to send an email, it calls POST /api/v1/emails with the account_id and message payload. Unipile routes the request through the correct provider: Gmail API for Google accounts, Microsoft Graph API for Outlook and Microsoft 365 accounts, and SMTP for IMAP accounts. The email is dispatched from the user's own mailbox and appears in their Sent folder.

The same API call works regardless of the provider. You write one integration; Unipile translates it to Gmail API, Microsoft Graph, or SMTP transparently.

Code examples

Python
Node.js
Python - Send email on behalf of user
import requests

# account_id retrieved after user completes OAuth flow
UNIPILE_DSN = "https://api1.unipile.com:13301"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
ACCOUNT_ID   = "user_account_id_from_db"

payload = {
    "account_id": ACCOUNT_ID,
    "to": [{
        "display_name": "Sarah Connor",
        "identifier":   "sarah@acme.com"
    }],
    "subject": "Following up on our conversation",
    "body":    "
Hi Sarah, just circling back...
 "
}

response = requests.post(
    f"{UNIPILE_DSN}/api/v1/emails",
    json=payload,
    headers={"X-API-KEY": ACCESS_TOKEN}
)

print(response.json())  # {"object": "EmailSent", "email_id": "..."}
Node.js - Send email on behalf of user
// account_id retrieved after user completes OAuth flow
const UNIPILE_DSN   = "https://api1.unipile.com:13301";
const ACCESS_TOKEN  = "YOUR_ACCESS_TOKEN";
const ACCOUNT_ID    = "user_account_id_from_db";

const payload = {
  account_id: ACCOUNT_ID,
  to: [{ display_name: "Sarah Connor", identifier: "sarah@acme.com" }],
  subject: "Following up on our conversation",
  body:    "
Hi Sarah, just circling back...
 "
};

const response = await fetch(`${UNIPILE_DSN}/api/v1/emails`, {
  method: "POST",
  headers: {
    "X-API-KEY":     ACCESS_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

const data = await response.json();
console.log(data); // { object: "EmailSent", email_id: "..." }

On-Behalf vs Transactional Email API: The Key Difference

These two categories of email API solve fundamentally different problems. Mixing them up is the most common mistake teams make when speccing out an email integration. Here is how they compare across every dimension that matters.

Criteria
On-Behalf (Unipile)
Transactional (SendGrid, etc.)
From address
User's real email address
Your platform's domain
Deliverability
User's SPF/DKIM reputation
Shared sending IP reputation
User consent required
Yes - OAuth 2.0 or IMAP credentials
No - platform owns the sender
Sent folder tracking
Appears in user's Sent folder
No - separate sending infrastructure
Reply threading
Native thread continuity
Manual Message-ID workarounds
Best for
CRM, AI assistants, support tools, sales automation
Password resets, receipts, marketing campaigns, notifications
Provider support
Gmail, Outlook, IMAP
Provider-agnostic SMTP
When to use each approach
Use an on-behalf API when the identity of the sender matters to the recipient - sales outreach, personalised follow-ups, support replies. Use a transactional API when the platform is the sender - password resets, invoices, system notifications. Many SaaS products need both: a transactional API for system emails and an on-behalf API for user-driven messages. For Gmail-specific implementation details, see the Gmail API send email guide. For Microsoft accounts, see the Outlook email API guide.

Build On-Behalf Email Sending with Unipile

Unipile provides a single unified API that abstracts Gmail, Outlook, and IMAP behind one consistent interface. You write one integration - Unipile handles provider-specific OAuth flows, token refresh, SMTP routing, and error handling for all three. Here is what is available for each provider.

Ready to add on-behalf email sending to your SaaS?
Free trial - no credit card required. Start sending in under 30 minutes.
Read the Email API Guide
Supported providers
Gmail
Google OAuth 2.0
Sends via Gmail API - full thread support
Google Workspace accounts supported
Attachments, CC, BCC, reply-to
Auto token refresh handled by Unipile
Gmail API send email guide
Outlook
Microsoft OAuth 2.0
Sends via Microsoft Graph API
Covers personal Outlook and Microsoft 365
Exchange Online fully supported
Attachments, CC, BCC, reply-to
Outlook email API guide
IMAP
Universal fallback
Sends via SMTP for any IMAP-compatible mailbox
Covers Yahoo, Fastmail, ProtonMail (IMAP bridge), and more
Same unified API endpoint as Gmail and Outlook
Credentials stored encrypted, never exposed to your app
IMAP API guide
How to get started in 4 steps
1 Create a Unipile account at dashboard.unipile.com and retrieve your DSN and API key.
2 Generate a hosted auth link for your user. Unipile handles the OAuth redirect to Gmail or Outlook, or displays the IMAP credentials form.
3 Store the account_id returned after the user completes the flow. This is the stable identifier for all future operations on that mailbox.
4 Call POST /api/v1/emails with the account_id and message payload. The email is sent from the user's own mailbox, through their provider's infrastructure.
Build On-Behalf Email Sending Today Read the API docs

Send Email On Behalf of User API - FAQ

Common questions about on-behalf email sending with Unipile

Yes, provided the user explicitly grants permission. On-behalf email sending is built on OAuth 2.0 (for Gmail and Outlook) or explicit credential sharing (for IMAP). In both cases, the user knowingly authorises your application to send from their mailbox. This is the same mechanism used by every major email client and productivity tool.

The key compliance requirements are:

  • The user must actively consent before you send anything on their behalf
  • Your privacy policy must disclose that you access and send from the user's mailbox
  • The user must be able to revoke access at any time (OAuth revocation or account disconnection)
  • You must not send content that violates the provider's terms of service (e.g. spam)

It is not legal to send from someone's address without their consent. Unipile's OAuth-based linking flow ensures you always have explicit user authorisation before any send operation.

The recipient sees the user's own domain in the From field - not your platform's domain. This is the core value proposition of on-behalf sending. For example, if a sales rep with the address john@acme.com has linked their Gmail account, every email sent through your CRM via Unipile will show From: john@acme.com.

The email is dispatched through the user's actual mail provider (Gmail API, Microsoft Graph, or SMTP), which means:

  • SPF records pass because the sending IP is authorised by the user's domain
  • DKIM signatures are valid because the provider signs with the user's domain key
  • DMARC alignment passes for the same reasons

This is fundamentally different from a transactional API where you send from a shared infrastructure and the recipient sees your platform's domain.

The required scopes depend on the provider. Unipile handles the OAuth consent screen automatically - your users see a standard Google or Microsoft permission dialog. The exact scopes requested are:

  • Gmail: the Gmail API scope that allows sending messages (https://mail.google.com/ or the more limited gmail.send scope if you only need send access)
  • Outlook / Microsoft 365: Microsoft Graph Mail.Send scope, plus Mail.ReadWrite if you also need to read or sync the inbox
  • IMAP: the user provides their IMAP hostname, port, username, and either their password or an app-specific password (required for accounts with two-factor authentication enabled)

Users can revoke these permissions at any time from their Google or Microsoft account security settings, or by disconnecting the linked account inside your product.

Yes. Any mailbox that can be authenticated via OAuth or IMAP credentials can be linked as a Unipile account. This includes:

  • Shared mailboxes in Microsoft 365 (e.g. support@company.com) - linked via a service account with the correct delegated permissions
  • Google Workspace shared inboxes and group addresses with Send As permissions configured
  • Any email alias that is handled by an IMAP-accessible mailbox

You can also customise the display name in the From field using the from parameter in the API payload, without changing the underlying sending address.

Unipile handles token refresh automatically for both Gmail and Outlook accounts. OAuth access tokens typically expire after one hour, but the refresh token is long-lived. When Unipile detects an expired access token before a send operation, it silently requests a new one using the stored refresh token - your application never sees this happen and the send call succeeds normally.

The only time you need to prompt the user to re-authenticate is if they have manually revoked access from their Google or Microsoft account settings. Unipile surfaces this as an account status change which you can detect via webhook or by polling the account endpoint.

Still have questions? Our team is here to help.

Talk to an expert
en_USEN
fr_FRFR es_ESES de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR en_USEN