Email API: Complete Guide for Developers (2026)

Email API Integration: From OAuth to Real-Time Sync

A real-world Email API integration follows four phases regardless of which provider you target. Read this section as a checklist before starting your implementation: skipping any step here is the most common reason integrations work in dev and break in production.

OAuth 2.0 Authentication

Both Gmail and Microsoft Graph use the standard OAuth 2.0 authorization code flow. The mechanics are identical: redirect the user to the provider, receive a one-time code on your callback URL, exchange it for a long-lived refresh token server-side, then use that refresh token to mint short-lived access tokens for every subsequent API call.

• Redirect the user to the provider's authorization endpoint with your client_id, redirect_uri, and the requested scope.
• The user grants permissions, the provider redirects to your callback URL with a one-time code parameter.
• Your server exchanges that code for an access_token (1 hour lifespan) and a refresh_token via a back-channel POST.
• Store the refresh_token securely server-side, encrypted at rest. This is the long-lived credential you use to generate new access tokens automatically.

Send & Receive Emails

Once authenticated, the next two operations cover 80% of typical Email API usage: fetching the inbox and sending a message. With Unipile's unified API, both work identically across Gmail, Outlook, and IMAP through a single set of endpoints.

# Fetch the latest 50 emails from a connected inbox
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: YOUR_API_KEY'

# Send a plain text email
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "YOUR_ACCOUNT_ID",
    "subject": "Hello from Unipile",
    "body": "Hello, this is a plain text email",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

Unipile also supports the typical advanced send features developers expect: attachments (multipart form-data with multiple files), custom headers (passing arrays of X- prefixed headers), reply-in-thread (using the original message's provider_id), display name override, allowed sender aliases, and open / link tracking with real-time webhook events. Each of these maps to a single field in the request body, no protocol negotiation required.

# Send with attachments + custom headers + tracking
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --form 'account_id=YOUR_ACCOUNT_ID' \
  --form 'subject=Contract draft' \
  --form 'body=Please find the v3 attached.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/path/to/contract.pdf' \
  --form 'attachments=@/path/to/appendix.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Real-Time Email Sync

Inbox synchronization is the most complex part of any email integration, and the most often misunderstood. A robust email sync implementation has three distinct phases: initial sync, incremental sync, and real-time webhook notifications. Skipping any of them produces an integration that works on day one and breaks at scale.

Plan for renewals from day one: Gmail Pub/Sub watch subscriptions expire after 7 days and must be renewed. Microsoft Graph subscriptions on mail resources expire after a maximum of about 3 days. Build subscription renewal into your background job infrastructure before going to production, otherwise your integration will silently stop receiving events.

Webhooks & Events

Webhooks are how a modern Email API tells your backend something happened, in real time, without you having to ask. Instead of polling /messages every 30 seconds (expensive and slow), you subscribe once, and the provider pushes a JSON payload to your endpoint every time a new email arrives, gets read, gets replied to, or gets deleted.

The events you typically subscribe to are mail_received (a new message landed in the inbox), mail_sent (an outgoing message was successfully delivered), mail_opened (the recipient opened it, if tracking is enabled), mail_link_clicked (the recipient clicked a tracked link), and account_status (the connected mailbox needs reauthentication, e.g. after a password change). Each event carries enough context for your downstream systems to react without making additional API calls.