directus-extension-send-email-via-gmail-api

Gmail Message Operation for Directus Flows

This custom Directus operation extension allows you to send Gmail messages or create Gmail drafts directly inside Directus Flows, including support for multiple file attachments from your directus_files collection.

✨ Features

• Send a Gmail message or create a draft (send or draft action).
• Support for to, cc, bcc, reply-to, in-reply-to, references, and threadId headers.
• Send both plain text and HTML message bodies.
• Attach multiple Directus files (directus_files) — files are read, base64-encoded, and properly attached as MIME parts.
• Full error logging for debugging Gmail API responses.

📝 Usage

In your Flow, add the “Gmail: Send or Draft” operation. Fill in the required fields:

• Access Token: Gmail OAuth 2.0 access token with the correct scopes.
• Action: Send a message or create a draft.
• Recipients: To, Cc, Bcc, etc.
• Subject / Body: Content of your email (plain text or HTML).
• Attachments: List of directus_files IDs (as JSON array, e.g. ["uuid1", "uuid2"]).

🔐 Environment Variables

This extension requires access to your Directus instance in order to fetch binary file contents for attachments. Set the following variables in your Directus .env file:

# Public URL of your Directus instance
PUBLIC_URL=https://your-directus.example.com

# A Directus admin static token (needed to download files internally)
ADMIN_TOKEN=your-admin-static-token

Note: This token is only used server-side to fetch file contents. It should not be exposed to clients.

🔑 Gmail OAuth 2.0

⚠️ Important: This extension does not handle the OAuth 2.0 flow itself. You must obtain and refresh Gmail access tokens outside of Directus.

• Required scopes:

  • https://www.googleapis.com/auth/gmail.send (to send messages)
  • https://www.googleapis.com/auth/gmail.compose (to create drafts)

• The accessToken must be provided manually in the Flow operation configuration (or injected dynamically via Flow variables).

📤 Gmail API Endpoints Used

• Send Message: POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
• Create Draft: POST https://gmail.googleapis.com/gmail/v1/users/me/drafts

The extension builds a valid MIME message, encodes it in base64url, and sends it to the Gmail API.

🐞 Troubleshooting

• Attachments not working → Ensure PUBLIC_URL and ADMIN_TOKEN are correctly set in .env.
• OAuth error / Unauthorized → Check that the accessToken you provide has not expired and contains the proper scopes.
• Invalid MIME → Verify that you selected text or html correctly for the body type.

📜 License

MIT © Dan Denolf