Send email with Gmail through Courier

Gmail is for testing and small internal sends.
Google caps daily sends at 500 on consumer Gmail and 2,000 on Workspace. It may suspend accounts sending bulk email through the API, and OAuth tokens expire. For production use , , or .

Prerequisites

A Gmail or Google Workspace inbox

Setup

When you connect your Gmail account, Courier requests permission to send emails on your behalf. Courier sends nothing until you make a send request using the provider.

OAuth authorization

Google APIs use OAuth for authentication and authorization. Once you grant permission, Courier requests an access token from the Google Authorization Server and sends the token to the Google Gmail API on your behalf. To grant permission, sign into the Gmail inbox you want to send from and consent to Courier’s requested Gmail scopes.

Gmail always sends as the authorized inbox, so a template’s From field has no effect here. Set the display name with the integration’s From Name, or override it per send with override.body.fromName. To change the address, authorize a different inbox.

Updating authorized account

On the page, click “Authorize a different Gmail inbox” to send from another account. You must grant permissions again every time you change the account. Addressing a recipient and sending are the same on every email provider, so they are documented once: and .

Overrides

covers the two levels and which one wins. lists the fields every email provider takes. In override.body you can set subject, text, fromName, replyTo, cc, and bcc. Each replaces the value Courier rendered. You can also override the request itself with override.headers, override.method, and override.url, and supply a token directly with override.config.access_token.

const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      gmail: {
        override: {
          body: {
            subject: "Overridden subject",
            replyTo: "support@acme-corp.com",
            bcc: "archive@acme-corp.com",
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "gmail": {
                "override": {
                    "body": {
                        "subject": "Overridden subject",
                        "replyTo": "support@acme-corp.com",
                        "bcc": "archive@acme-corp.com",
                    },
                },
            },
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "providers": {
        "gmail": {
          "override": {
            "body": {
              "subject": "Overridden subject",
              "replyTo": "support@acme-corp.com",
              "bcc": "archive@acme-corp.com"
            }
          }
        }
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      gmail: {
        override: {
          body: {
            subject: "Overridden subject",
            replyTo: "support@acme-corp.com",
            bcc: "archive@acme-corp.com"
          }
        }
      }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Providers: shared.MessageProvidersParam{
			"gmail": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"subject": "Overridden subject",
						"replyTo": "support@acme-corp.com",
						"bcc": "archive@acme-corp.com",
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("gmail", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "body", java.util.Map.of(
                        "subject", "Overridden subject",
                        "replyTo", "support@acme-corp.com",
                        "bcc", "archive@acme-corp.com"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'providers' => [
      'gmail' => [
        'override' => [
          'body' => [
            'subject' => 'Overridden subject',
            'replyTo' => 'support@acme-corp.com',
            'bcc' => 'archive@acme-corp.com',
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "gmail",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "body": {
                            "subject": "Overridden subject",
                            "replyTo": "support@acme-corp.com",
                            "bcc": "archive@acme-corp.com"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"gmail": {"override": {"body": {"subject": "Overridden subject", "replyTo": "support@acme-corp.com", "bcc": "archive@acme-corp.com"}}}}'

With Courier MCP, send my template to sarah@acme-corp.com and override the Gmail subject and reply-to.

Courier handles OAuth authorization and token refresh, so you rarely need override.config.access_token.

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.

Provider details

gmail

Courier recommends routing to the channel. Naming this key in routing.channels instead is supported, and sends through just this provider.

Send to a specific provider

When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

Get started

Available integrations

Send email with Gmail through Courier

Prerequisites

Setup

OAuth authorization

Updating authorized account

Overrides

Troubleshooting

All Gmail sends failing with “request failed with status code 400”

Provider details

Send to a specific provider

​Prerequisites

​Setup

​OAuth authorization

​Updating authorized account

​Overrides

​Troubleshooting

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

​Provider details

Send to a specific provider

Prerequisites

Setup

OAuth authorization

Updating authorized account

Overrides

Troubleshooting

All Gmail sends failing with “request failed with status code 400”

Provider details