Phoenix API Platform

Gmail-backed email API · Node.js

Gmail API integration with Node.js for transactional email

Looking for a Gmail API integration for your application? Phoenix exposes a server-side email endpoint backed by its configured Gmail provider. Your application calls Phoenix to send account notifications, receipts and service messages without placing Gmail OAuth credentials in browser code.

Email APIGmail-backed providerNode.jsServer-side

What is the difference between Gmail API and an email API?

The Gmail API is Google's interface for software authorized to access a Gmail account. An email API is an application-facing interface for sending messages through an email provider. Phoenix provides a server-side email API that uses a configured Gmail connection for delivery; your service key authenticates your application to Phoenix.

This does not make Phoenix a substitute for Google OAuth setup or Gmail account requirements. The email provider credentials and sender configuration must be managed on the platform server, and Gmail sending limits and policies still apply.

Send an email from Node.js with Phoenix

Activate the email service, create a production API key with the email:send permission and store it on your server. Configure PHOENIX_API_BASE_URL for your environment. Each message send requires an Idempotency-Key.

import { randomUUID } from 'node:crypto';

const apiBase = process.env.PHOENIX_API_BASE_URL
  || 'https://phoenixapiplatform.onrender.com';
const apiKey = process.env.PHOENIX_EMAIL_API_KEY;
if (!apiKey) throw new Error('Missing Phoenix email API key');

const response = await fetch(`${apiBase}/v1/email/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({
    to: 'customer@example.com',
    subject: 'Your order update',
    text: 'Your order has been received.',
  }),
});

if (!response.ok) {
  throw new Error(`Phoenix request failed: HTTP ${response.status}`);
}

const result = await response.json();
console.log('Email request accepted:', result.data.externalId);

The API returns HTTP 202 for an accepted send request. Check message records through GET /v1/email/messages using a key with email:read. Acceptance by the API or provider is not a guarantee of inbox placement.

Protect credentials and make retries safe

  • Never expose Phoenix API keys, Gmail client secrets or refresh tokens in frontend code.
  • Use a new idempotency key for a new message, and reuse the original key when retrying the same request.
  • Check the email service is active and has sufficient credits.
  • Monitor message status and investigate provider rejections or delivery issues.
  • Use a sender identity and message content that comply with Gmail and applicable email rules.

When Phoenix may fit

Phoenix may fit developers who want to call a single backend API for transactional email while also managing SMS and Mobile Money integrations in a developer workspace. Confirm account setup, provider readiness, service credits and current pricing before production use.

Explore the Phoenix API Platform and the SMS API guide for Uganda.