Send email with SendGrid through Courier

Prerequisites

A SendGrid account

Setup

Create an API key in SendGrid

In SendGrid, open API Keys and create a key with Mail Send permission. Copy it.

Mail Send is all Courier needs to send email, and all the event webhook needs to report delivered. Two optional features want more: template import needs Template Engine, and Email Activity polling needs read access to Email Activity.

Add it to Courier

Open the page, select the SendGrid integration, and paste the key into API Key.

Set a From Address and save

Add the address SendGrid sends from, such as noreply@acme-corp.com. Select Add Integration, then Save.

Addressing a recipient and sending are the same on every email provider, so they are documented once: and .

Send an email

Address the recipient by email and Courier routes it to SendGrid.

const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {
      name: "Sarah Bennett",
    },
  },
});

response = client.send.message(
    message={
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {
            "name": "Sarah Bennett",
        },
    },
)

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",
      "data": { "name": "Sarah Bennett" }
    }
  }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" }
  }
)

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"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("name", "Sarah Bennett")))
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['name' => 'Sarah Bennett'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
    },
};

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.data '{"name": "Sarah Bennett"}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to sarah@acme-corp.com by email.

Overrides

covers the two levels and which one wins. lists the fields every email provider takes. An override changes the request Courier sends to SendGrid. Use one to set a field Courier doesn’t support yet, or to replace a value Courier generates.

Key	What it replaces
`override.body`	Merged into SendGrid’s `/mail/send` request body. Any field that endpoint accepts works here.
`override.config.apiKey`	The API key for this one send, instead of the key saved on the integration.

Nest either under providers.sendgrid on the message:

const { requestId } = await courier.send.message({
  message: {
    to: {
      email: "sarah@acme-corp.com",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      sendgrid: {
        override: {
          body: {
            subject: "Your appointment reminder",
            attachments: [
              {
                content: "eyJmb28iOiJiYXIifQ==",
                type: "application/json",
                filename: "appointment-details.json",
              },
            ],
          },
        },
      },
    },
  },
});

response = client.send.message(
    message={
        "to": {
          "email": "sarah@acme-corp.com",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "providers": {
            "sendgrid": {
                "override": {
                  "body": {
                    "subject": "Your appointment reminder",
                    "attachments": [
                      {
                        "content": "eyJmb28iOiJiYXIifQ==",
                        "type": "application/json",
                        "filename": "appointment-details.json",
                      },
                    ],
                  },
                },
            },
        },
    },
)

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": {
          "sendgrid": {
            "override": {
              "body": {
                "subject": "Your appointment reminder",
                "attachments": [
                  {
                    "content": "eyJmb28iOiJiYXIifQ==",
                    "type": "application/json",
                    "filename": "appointment-details.json"
                  }
                ]
              }
            }
          }
        }
      }
    }'

response = courier.send_.message(
  message: {
    to: {
      email: "sarah@acme-corp.com"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    providers: {
      "sendgrid" => {
        override: {
          body: {
            subject: "Your appointment reminder",
            attachments: [
              {
                content: "eyJmb28iOiJiYXIifQ==",
                type: "application/json",
                filename: "appointment-details.json"
              }
            ]
          }
        }
      }
    }
  }
)

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{
			"sendgrid": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"body": map[string]any{
						"subject": "Your appointment reminder",
						"attachments": []any{
							map[string]any{
								"content": "eyJmb28iOiJiYXIifQ==",
								"type": "application/json",
								"filename": "appointment-details.json",
							},
						},
					},
				},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("sendgrid", JsonValue.from(java.util.Map.of(
                "override", java.util.Map.of("body", java.util.Map.of("subject", "Your appointment reminder", "attachments", java.util.List.of(java.util.Map.of("content", "eyJmb28iOiJiYXIifQ==", "type", "application/json", "filename", "appointment-details.json")))))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'template' => "nt_01kx4h2jdafq8bk9aftxak4b40",
    'providers' => [
      'sendgrid' => [
        'override' => [
          'body' => [
            'subject' => 'Your appointment reminder',
            'attachments' => [
              [
                'content' => 'eyJmb28iOiJiYXIifQ==',
                'type' => 'application/json',
                'filename' => 'appointment-details.json',
              ],
            ],
          ],
        ],
      ],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "sendgrid",
                new()
                {
                    Override = new Dictionary<string, JsonElement>()
                    {
                        { "body", JsonSerializer.SerializeToElement(new { subject = "Your appointment reminder", attachments = new[] { new { content = "eyJmb28iOiJiYXIifQ==", type = "application/json", filename = "appointment-details.json" } } }) },
                    },
                }
            },
        },
    },
};

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 '{"sendgrid": {"override": {"body": {"subject": "Your appointment reminder", "attachments": [{"content": "eyJmb28iOiJiYXIifQ==", "type": "application/json", "filename": "appointment-details.json"}]}}}}'

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

Template import

Import your SendGrid templates from the .

Importing SendGrid Dynamic Templates needs three things:

Templates saved as SendGrid Dynamic Templates.
A SendGrid API key with full access permissions for Template Engine.
Your SendGrid credentials on the configuration page, so Courier can retrieve the templates.

Import process

With those permissions, the import tool lists your templates as checkboxes. Select the ones to import.

Delivery tracking

Delivery tracking is off until you set it up. Until then a working SendGrid integration leaves every message at SENT, because Courier has sent the email but has heard nothing back. See . SendGrid can report two ways, and the webhook below is the better one:

	Event webhook	Email Activity polling
Speed	Real time	On a schedule
API key permission	Mail Send only	Read access to Email Activity
SendGrid add-on	None	The email-history add-on (paid)
Available on EU SendGrid	Yes	No, EU SendGrid has no Email Activity API

Use the webhook. Reach for polling only if you can’t add one, and not at all on EU SendGrid.

Get Webhook URL

In Courier, open the from the Channels menu. It shows a Webhook URL.

Configure SendGrid Webhook

Copy the webhook URL, then log in to SendGrid. Choose Settings, then Mail Settings, then Event Webhooks.Click Create new webhook and fill out the form:

Friendly Name - Whatever you like
Post URL - Paste the URL you copied from Courier.
Deliverability Data - Check all 5 boxes.
Security features - Leave these disabled. The HTTPS URL you pasted carries a cryptographic token Courier uses to verify that incoming events are yours.

Press Save.

Turn polling off

With the webhook live you no longer need Courier to poll. Wait about an hour first, so in-flight messages don’t lose their status updates.Then return to the and switch off Enable polling for status updates and Enable Email Activity Tracking via Polling. Press Save.

Email Activity polling

Polling is the fallback when you can’t add a webhook. Switch on Enable Email Activity Tracking via Polling in the integration settings, and Courier queries SendGrid’s Email Activity API on a schedule for each message’s status. It needs two things on the SendGrid side, and both are easy to miss:

Read access to Email Activity, on the API key.

The email-history add-on, on the SendGrid plan.

If either is missing, SendGrid rejects the query and Courier turns the toggle back off, showing a “Tracking Disabled” callout while messages stay at SENT. EU accounts hit this every time, since EU SendGrid has no Email Activity API. Use the webhook there.

Troubleshooting

Check the to debug provider errors. For anything else, contact Courier Support.

SendGrid API Key Access Forbidden

Your API key doesn’t cover the request. Check it against SendGrid’s allowed API key actions.

Solution

Either stay within the actions your key allows, or create a new key that covers the ones you need.Creating a new SendGrid API key with the permissions you wantIn the SendGrid API keys console, select “Create API Key,” then select the permissions in SendGrid’s API key settings.

SendGrid offers three permission scopes:

Full Access
Restricted Access
Billing Access.

You can also set the access level for each one.

Error: sendgrid invalid email

You get this error when the address breaks internet email formatting standards, or doesn’t exist on the recipient’s mail server. It can come from your server or the receiver’s.SendGrid checks the format before sending. If the receiving server can’t find the address, it returns a 550 bounce.Addresses go invalid for several reasons:

Typos or formatting errors in the address.
The user changed addresses and left the old one empty. Inactivity and lack of engagement are the biggest cause.
The inbox provider went out of business, or its server went down for good. Every address on that dead domain is invalid.

Solution

Scrub your email lists with an email verification tool to raise deliverability and engagement.
Sort your list by why each address signed up. Irrelevant or out-of-date email lowers open and click-through rates.
Group contacts by level of engagement. If an address looks like graymail, confirm it is still valid. If not, add it to the unsubscribe list.
Create a sunset policy, so you find disengaged contacts regularly and either remove or re-engage them.

Maximum Credits Exceeded SendGrid

SendGrid credits are the emails you can send. One credit per email, renewed at the start of each month. Exceeding your account’s limit raises this error in SendGrid’s SMTP troubleshooting guide.

Solution

Wait for your quota to renew, or upgrade your SendGrid plan for more credits.

SendGrid 535 Authentication Failed Bad Username Password

Three causes:

The username or password in the email client is wrong. The wrong mail server can also cause this.
The account is disabled, often for past-due payment or spam complaints.
SMTP authentication isn’t enabled in your email client.

Solution

Check your username and password, billing plan, and account status.
Check that you confirmed your email address.
Configure SMTP authentication.
Store your API keys as environment variables. You then change a key in one place instead of hunting for every use.
Set up sender authentication for your domains, which gives you SPF and DKIM on the Twilio SendGrid account.

Sendgrid From Field Not Working

The from address doesn’t match a verified Sender Identity. No email sends until you fix it.

Solution

Authenticate your sender identities in SendGrid’s sender authentication guide. A sender identity is the address recipients see as the sender. Authenticate one or more with Domain Authentication or Single Sender Verification.

Provider details

sendgrid

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 SendGrid through Courier

Prerequisites

Setup

Send an email

Overrides

Template import

Import process

Delivery tracking

Email Activity polling

Troubleshooting

Solution

Solution

Solution

Solution

Solution

Provider details

Send to a specific provider

​Prerequisites

​Setup

​Send an email

​Overrides

​Template import

​Import process

​Delivery tracking

​Email Activity polling

​Troubleshooting

​Solution

​Solution

​Solution

​Solution

​Solution

​Provider details

Send to a specific provider

Prerequisites

Setup

Send an email

Overrides

Template import

Import process

Delivery tracking

Email Activity polling

Troubleshooting

Solution

Solution

Solution

Solution

Solution

Provider details