Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Gmail is intended for testing and small-scale internal sends only. Google enforces daily send limits (500/day for consumer Gmail, 2,000/day for Workspace), may flag or suspend accounts sending bulk email via the Gmail API, and OAuth tokens require periodic re-authorization. For production email delivery, use a dedicated transactional provider like SendGrid, AWS SES, or Postmark.

​
Setup

When you set up Gmail as a provider and connect your Gmail account, Courier will request permission to send emails on your behalf. Courier will not send any emails unless you explicitly make a send request using the provider.

​
OAuth Authorization

Google APIs use the OAuth protocol for authentication and authorization. Once given permission, Courier will request an access token from the Google Authorization Server, and send the token to the Google Gmail API on your behalf. To give Courier access to your Gmail credentials, you will need to consent to Courier’s requested Gmail scopes by signing into your desired Gmail inbox and allowing Courier permission.

​
Updating Authorized Account

On the Gmail Integration page, you can click on “Authorize a different Gmail inbox” to send messages from a different account. This will require you to give permissions for the new email account every time you change the account.

​
Profile Requirements

To deliver a message to a recipient over Gmail, Courier must be provided the recipient’s email address. This value should be included in the recipient profile as email. 
{
  "message": {
    // Recipient Profile
    "to": {
      "email": "alice@acme.com"
    }

    // ... rest of message definition
  }
}

​
Overrides

Gmail does not support provider-level body overrides. OAuth authorization and token refresh are handled automatically by Courier.

​
Troubleshooting

​
All Gmail sends failing with “Request failed with status code 400”

This error means Courier’s stored OAuth refresh token is no longer valid. Google rejected the token refresh with a 400 invalid_grant response, so all subsequent sends fail as UNDELIVERABLE. Common causes:
  • The Gmail account password was changed
  • A Google Workspace admin revoked Courier’s OAuth access
  • Google revoked the token due to inactivity or a security review
  • The Google Cloud project’s OAuth consent screen is in “Testing” mode (tokens expire after 7 days)
How to confirm: In Courier, check the message timeline for a Gmail-routed message. If you see UNDELIVERABLE with the error "Request failed with status code 400" and willRetry: false, the refresh token is dead. Fix: Go to Channels → Gmail in Courier Studio, click Update next to the authorized account, and re-authorize with your Google account. This issues a fresh access token and refresh token, restoring sends immediately.
If the Gmail channel is configured with routing fallback, messages that fail on Gmail will fall through to the next configured channel (e.g., Courier Inbox). Only the Gmail delivery path is affected.