Email Connectors API reference

Overview & Authentication

A standalone service to connect an email account, send, and receive across three providers. The three connectors share one API — your app always calls the same /send and /fetch; only the one-time connect step differs per provider (imap_smtp, outlook, or google).

Item	Value
Base URL	https://integrationapplication.atozemail.com/api/v1
Auth header	x-api-key: <API_KEY> (or ?api_key= for browser links)
Content-Type	application/json for POST bodies
Transport	HTTPS only (trusted cert); HTTP redirects to HTTPS. Port 443 (8080 also serves same cert)

Last updated: 2026-07-14

Response format & status codes

Success

json

{
  "success": true,
  "data": { }
}

Error

json

{
  "success": false,
  "error": {
    "code": "STRING",
    "message": "..."
  }
}

Status	Meaning
200	OK
400	Bad request / missing fields
401	Bad API key
404	Account not found
502	Upstream send/fetch failed
500	Server / DB error

Health (no auth)

Request

bash

curl https://integrationapplication.atozemail.com/healthz

Response

json

{"status":"ok"}

GET/healthz

Health check (no auth)

Try it

https://integrationapplication.atozemail.com/healthz

Proxied server-side with your configured API key (no auth for this endpoint).

Common account endpoints

Account operations work for all providers. Responses show provider and conn_status; passwords and tokens are never returned.

GET/api/v1/accounts

List all accounts

GET/api/v1/accounts/{email}

Get one account

DELETE/api/v1/accounts/{email}

Delete an account

List all accounts

Request

bash

curl https://integrationapplication.atozemail.com/api/v1/accounts \
  -H "x-api-key: <API_KEY>"

GET/api/v1/accounts

List all connected accounts

Try it

https://integrationapplication.atozemail.com/api/v1/accounts

Proxied server-side with your configured API key.

Get one account

Request

bash

curl https://integrationapplication.atozemail.com/api/v1/accounts/USER@DOMAIN.com \
  -H "x-api-key: <API_KEY>"

GET/api/v1/accounts/{email}

Get one account by email

Try it

https://integrationapplication.atozemail.com/api/v1/accounts/{email}

Email *

Proxied server-side with your configured API key.

Delete an account

Request

bash

curl -X DELETE https://integrationapplication.atozemail.com/api/v1/accounts/USER@DOMAIN.com \
  -H "x-api-key: <API_KEY>"

DELETE/api/v1/accounts/{email}

Remove a connected account

Try it

https://integrationapplication.atozemail.com/api/v1/accounts/{email}

Email *

Proxied server-side with your configured API key.

Unified send — POST /send

Works for all providers. The service auto-selects SMTP, Microsoft Graph, or Gmail API from the connected from account.

Request

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/send \
  -H "x-api-key: <API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "from": "USER@DOMAIN.com",
    "to": "recipient@example.com",
    "subject": "Hello",
    "html": "<p>Body</p>"
  }'

Response

json

{
  "success": true,
  "data": {
    "messageId": "<...>",
    "accepted": ["recipient@example.com"],
    "rejected": null
  }
}

IMAP/SMTP & Google return a real Message-ID. Outlook (Graph /sendMail) returns an empty messageId — locate Outlook messages by subject. Errors: 404 (from not connected), 502 (send failed).

POST/api/v1/send

Send email from a connected account

Try it

https://integrationapplication.atozemail.com/api/v1/send

From *To *Subject *HTML body *

Proxied server-side with your configured API key.

Unified fetch — POST /fetch

Searches Inbox + Spam/Junk; returns placement + SPF/DKIM/DMARC. Match by messageId (exact, preferred) or subject (substring).

Request (by subject)

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/fetch \
  -H "x-api-key: <API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "email": "USER@DOMAIN.com",
    "subject": "Hello"
  }'

Request (by messageId)

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/fetch \
  -H "x-api-key: <API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "email": "USER@DOMAIN.com",
    "messageId": "<abc@sender.com>"
  }'

Response

json

{
  "success": true,
  "data": {
    "count": 1,
    "emails": [
      {
        "messageId": "abc@sender.com",
        "subject": "Hello",
        "from": "sender@example.com",
        "to": "USER@DOMAIN.com",
        "date": "2026-07-02T08:00:00Z",
        "folder": "inbox",
        "receivingIp": "1.2.3.4",
        "spf": "pass",
        "dkim": "pass",
        "dmarc": "pass",
        "rawHeaders": "..."
      }
    ]
  }
}

Not found: { "success": true, "data": { "count": 0, "emails": null } }. Errors: 404 (account not connected), 502 (fetch failed). After /send, delivery can take a few seconds — poll /fetch until count > 0.

folder values: inbox, spam, trash. SPF/DKIM/DMARC may be pass, fail, softfail, neutral, or unknown.

POST/api/v1/fetch

Fetch emails from Inbox + Spam/Junk

Try it

https://integrationapplication.atozemail.com/api/v1/fetch

Mailbox email *Subject (substring)Message-ID (exact)

Proxied server-side with your configured API key.

Connector A — IMAP / SMTP Working

Standard mailboxes (host + port + user + password). No OAuth. Connect validates IMAP + SMTP, then stores; passwords encrypted at rest.

POST/api/v1/accounts

Connect + validate + store

POST/api/v1/accounts/test-imap

Validate IMAP (no store)

POST/api/v1/accounts/test-smtp

Validate SMTP (no store)

Connect

Request

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/accounts \
  -H "x-api-key: <API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "email": "USER@DOMAIN.com",
    "imap_host": "imap.domain.com",
    "imap_port": 993,
    "imap_username": "USER@DOMAIN.com",
    "imap_password": "secret",
    "smtp_host": "smtp.domain.com",
    "smtp_port": 587,
    "smtp_username": "USER@DOMAIN.com",
    "smtp_password": "secret"
  }'

→ 200 with the stored account (conn_status: "valid"); or 400 IMAP_FAILED / SMTP_FAILED.

POST/api/v1/accounts

Connect IMAP/SMTP account (validates + stores)

Try it

https://integrationapplication.atozemail.com/api/v1/accounts

Email *IMAP host *IMAP port *IMAP username *IMAP password *SMTP host *SMTP port *SMTP username *SMTP password *

Proxied server-side with your configured API key.

Validate without storing

POST /api/v1/accounts/test-imap with host, port, username, password. Same shape for POST /api/v1/accounts/test-smtp. Then use unified /send and /fetch.

Test IMAP

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/accounts/test-imap \
  -H "x-api-key: <API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "host": "imap.domain.com",
    "port": 993,
    "username": "USER@DOMAIN.com",
    "password": "secret"
  }'

Test SMTP

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/accounts/test-smtp \
  -H "x-api-key: <API_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "host": "smtp.domain.com",
    "port": 587,
    "username": "USER@DOMAIN.com",
    "password": "secret"
  }'

POST/api/v1/accounts/test-imap

Validate IMAP credentials (no store)

Try it

https://integrationapplication.atozemail.com/api/v1/accounts/test-imap

Host *Port *Username *Password *

Proxied server-side with your configured API key.

POST/api/v1/accounts/test-smtp

Validate SMTP credentials (no store)

Try it

https://integrationapplication.atozemail.com/api/v1/accounts/test-smtp

Host *Port *Username *Password *

Proxied server-side with your configured API key.

Connector B — Outlook (OAuth / Microsoft Graph) Needs Azure admin consent

For Microsoft 365 / Outlook mailboxes.

One-time Azure setup

App AirMTA-Graph (client b197082d-3bc7-4e23-b24b-22277bc1eb95).
Add redirect URI (App registration → Authentication → Web): https://integrationapplication.atozemail.com/api/v1/oauth/outlook/callback
Mailbox must be in a tenant the app allows; tenant admin may need to Grant admin consent once.

Connect

Open in a browser — one click to Microsoft sign-in:

Authorize URL

text

https://integrationapplication.atozemail.com/api/v1/oauth/outlook/authorize?email=USER@DOMAIN.com&api_key=<API_KEY>

→ sign in → consent → "Outlook account connected". Then use unified /send and /fetch.

The api_key in a URL lands in browser history — prefer the x-api-key header for programmatic calls. OAuth authorize links are the exception.

Connector C — Google (OAuth / Gmail API) Ready

For Gmail / Google Workspace mailboxes.

One-time Google Cloud setup

OAuth client 1043361905522-vni3crhd02nvip185q3i0dltjqqcgbd2.apps.googleusercontent.com (project 1043361905522).
Redirect URI (already registered): https://integrationapplication.atozemail.com/api/v1/oauth/google/callback
Scopes: gmail.send + gmail.readonly (restricted) and calendar.events + calendar.readonly (sensitive), plus openid email profile.
Publishing status: "In production" = any user; "Testing" = test users only, refresh token expires in 7 days.

Connect

Open in a browser — one click to Google sign-in:

Authorize URL

text

https://integrationapplication.atozemail.com/api/v1/oauth/google/authorize?email=USER@gmail.com&api_key=<API_KEY>

Refresh token tip

If Google returns no refresh token (account already consented before), revoke the app at myaccount.google.com/permissions and reconnect so consent is fresh.

→ sign in → consent → "Google account connected". Then use unified /send and /fetch.

User-level API (Supabase JWT)

A second surface, scoped to the signed-in user instead of the shared service key. Authenticate every call with the user's Supabase session token: Authorization: Bearer <SUPABASE_JWT>. A user only ever sees their own connected accounts. connection_id is the id returned by GET /google/accounts.

Status	Meaning
401	Missing or expired JWT
403 missing_scope	Account lacks a Google permission — reconnect
404	Connection not found (or not yours)

Connect & manage Google accounts

POST/api/v1/google/connect

Start OAuth; returns the Google consent URL

GET/api/v1/google/accounts

List the user's connected accounts

DELETE/api/v1/google/accounts/{id}

Disconnect an account

Start connect (returns {url} to open in a browser)

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/google/connect \
  -H "Authorization: Bearer <SUPABASE_JWT>" \
  -H "content-type: application/json" \
  -d '{ "application_id": "<APPLICATION_ID>" }'

List connected accounts

bash

curl "https://integrationapplication.atozemail.com/api/v1/google/accounts?application_id=<APPLICATION_ID>" \
  -H "Authorization: Bearer <SUPABASE_JWT>"

Gmail endpoints

POST/api/v1/gmail/send

Send email as the connected account

GET/api/v1/gmail/messages

List recent messages

GET/api/v1/gmail/messages/{id}

Get one message

Send

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/gmail/send \
  -H "Authorization: Bearer <SUPABASE_JWT>" \
  -H "content-type: application/json" \
  -d '{
    "connection_id": "<CONNECTION_ID>",
    "to": "recipient@example.com",
    "subject": "Hello",
    "html": "<p>Body</p>"
  }'

List messages

bash

curl "https://integrationapplication.atozemail.com/api/v1/gmail/messages?connection_id=<CONNECTION_ID>&max_results=10" \
  -H "Authorization: Bearer <SUPABASE_JWT>"

Calendar endpoints

All event endpoints accept an optional calendar_id (from GET /calendar/calendars); omit it to use the account's primary calendar.

GET/api/v1/calendar/calendars

List the account's calendars

GET/api/v1/calendar/events

List events

POST/api/v1/calendar/events

Create an event

DELETE/api/v1/calendar/events/{id}

Delete an event

List calendars

bash

curl "https://integrationapplication.atozemail.com/api/v1/calendar/calendars?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer <SUPABASE_JWT>"

List events

bash

curl "https://integrationapplication.atozemail.com/api/v1/calendar/events?connection_id=<CONNECTION_ID>&max_results=10" \
  -H "Authorization: Bearer <SUPABASE_JWT>"

Create event

bash

curl -X POST https://integrationapplication.atozemail.com/api/v1/calendar/events \
  -H "Authorization: Bearer <SUPABASE_JWT>" \
  -H "content-type: application/json" \
  -d '{
    "connection_id": "<CONNECTION_ID>",
    "summary": "Team sync",
    "start": "2026-07-20T10:00:00Z",
    "end": "2026-07-20T10:30:00Z",
    "timeZone": "UTC"
  }'

Delete event

bash

curl -X DELETE "https://integrationapplication.atozemail.com/api/v1/calendar/events/<EVENT_ID>?connection_id=<CONNECTION_ID>" \
  -H "Authorization: Bearer <SUPABASE_JWT>"

Full endpoint summary

Service surface — x-api-key:

Method	Path	Purpose
GET	/healthz	Health (no auth)
GET	/api/v1/accounts	List accounts
GET	/api/v1/accounts/{email}	Get one account
DELETE	/api/v1/accounts/{email}	Remove account
POST	/api/v1/accounts	IMAP/SMTP connect + validate + store
POST	/api/v1/accounts/test-imap	Validate IMAP (no store)
POST	/api/v1/accounts/test-smtp	Validate SMTP (no store)
GET	/api/v1/oauth/outlook/authorize	Outlook connect (redirect to MS)
GET	/api/v1/oauth/outlook/callback	MS redirects here (auto, no auth)
GET	/api/v1/oauth/google/authorize	Google connect (redirect to Google)
GET	/api/v1/oauth/google/callback	Google redirects here (auto, no auth)
POST	/api/v1/send	Send (all providers)
POST	/api/v1/fetch	Read Inbox + Spam/Junk (all providers)

User-level surface — Authorization: Bearer:

Method	Path	Purpose
POST	/api/v1/google/connect	Start Google OAuth; returns consent URL
GET	/api/v1/google/oauth/callback	Google redirects here (auto, no auth)
GET	/api/v1/google/accounts	List the user's connected Google accounts
DELETE	/api/v1/google/accounts/{id}	Disconnect a Google account
POST	/api/v1/gmail/send	Send email via Gmail
GET	/api/v1/gmail/messages	List recent messages
GET	/api/v1/gmail/messages/{id}	Get one message
GET	/api/v1/calendar/calendars	List the account's calendars
GET	/api/v1/calendar/events	List calendar events
POST	/api/v1/calendar/events	Create a calendar event
DELETE	/api/v1/calendar/events/{id}	Delete a calendar event

Notes

One API, three providers — connect differs; /send and /fetch are identical.
Credentials at rest: IMAP/SMTP passwords and OAuth refresh tokens are AES-256-GCM encrypted; access tokens fetched on demand, never stored; secrets never returned.
Max request body: 25 MB.
SPF/DKIM/DMARC come from the receiving server's Authentication-Results header; they read unknown only for internal-only deliveries that omit that header.
The api_key in a URL lands in browser history — prefer the x-api-key header for programmatic calls.