> ## 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.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Send email with MailerSend through Courier

> Connect MailerSend with an API token and a verified sending domain, override any /v1/email field or add attachments, and fix 422 errors.

Keep MailerSend as your email provider. Courier sends through your MailerSend account and adds [templates](https://www.courier.com/docs/design/templates/overview.md), [user preferences](https://www.courier.com/docs/recipients/preferences/overview.md), [failover to a backup provider](https://www.courier.com/docs/send/routing.md#failover), [message logs](https://www.courier.com/docs/monitor/logs.md), and more channels like SMS, push, and [in-app Inbox](https://www.courier.com/docs/in-app/overview.md).

MailerSend bills you for email delivery, and Courier [bills per send](https://www.courier.com/docs/workspaces/billing.md).

## Prerequisites

* [A MailerSend account](https://www.mailersend.com/)
* A verified sending domain in MailerSend

## Setup

**1. Verify your domain**

In MailerSend, open [Domains](https://app.mailersend.com/domains), add your domain, and complete DNS verification.

![MailerSend Domains page listing a verified sending domain with processed, delivered, and rejected counts and a Manage button](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/mailersend-domains.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=64779cd2f355b73e5acc196bb87669ff)

**2. Generate an API token**

Click "Manage" on your domain and [generate an API token](https://www.mailersend.com/help/managing-api-tokens).

![MailerSend API token page listing an active full-access token named Integration Setup API, with Generate new token and Manage buttons](https://mintcdn.com/courier-4f1f25dc/xDJPBS8EQ58X_0-v/assets/mailersend-api-tokens.webp?fit=max\&auto=format\&n=xDJPBS8EQ58X_0-v\&q=85\&s=f4d58c3b1dd5bf2583deab92ada71d20)

**3. Configure in Courier**

In Courier, open the [MailerSend Integration](https://app.courier.com/integrations/catalog/mailersend) page. Enter your API token and From Address, then click "Save."

Addressing a recipient and sending are the same on every email provider, so they are documented once: [profile requirements](https://www.courier.com/docs/integrations/email/overview.md#profile-requirements) and [send to a recipient](https://www.courier.com/docs/integrations/email/overview.md#send-to-a-recipient).

## Overrides

[How overrides work](https://www.courier.com/docs/send/overrides.md#how-overrides-work) covers the two levels and which one wins. [Email channel overrides](https://www.courier.com/docs/integrations/email/overview.md#channel-overrides) lists the fields every email provider takes.

You can override any field MailerSend's [/v1/email endpoint](https://developers.mailersend.com/api/v1/email.html#send-an-email) supports. Use an override when Courier doesn't support a field yet, or to replace a value Courier generates.

This example swaps the API key and the sender in `config`:

```javascript Node.js highlight={8-15} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mailersend: {
        override: {
          config: {
            apiKey: "<your override API key>",
            fromAddress: "alternate-sender@yourdomain.com",
          },
        },
      },
    },
  },
});
```

```python Python highlight={8-15} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mailersend": {
                "override": {
                    "config": {
                        "apiKey": "<your override API key>",
                        "fromAddress": "alternate-sender@yourdomain.com",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={11-18} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mailersend": {
          "override": {
            "config": {
              "apiKey": "<your override API key>",
              "fromAddress": "alternate-sender@yourdomain.com"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-15} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mailersend: {
        override: {
          config: {
            apiKey: "<your override API key>",
            fromAddress: "alternate-sender@yourdomain.com"
          }
        }
      }
    }
  }
)
```

```go Go highlight={10-17} theme={null}
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{
			"mailersend": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"apiKey": "<your override API key>",
						"fromAddress": "alternate-sender@yourdomain.com",
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailersend", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "apiKey", "<your override API key>",
                        "fromAddress", "alternate-sender@yourdomain.com"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-15} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mailersend' => [
        'override' => [
          'config' => [
            'apiKey' => '<your override API key>',
            'fromAddress' => 'alternate-sender@yourdomain.com',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-24} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailersend",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "apiKey": "<your override API key>",
                            "fromAddress": "alternate-sender@yourdomain.com"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

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

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mailersend": {"override": {"config": {"apiKey": "<your override API key>", "fromAddress": "alternate-sender@yourdomain.com"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com and set a MailerSend field Courier does not expose.
```

### Attachments

Add an `attachments` array in the override. File content must be base64-encoded.

```javascript Node.js highlight={8-18} theme={null}
const { requestId } = await courier.send.message({
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com",
    },
    providers: {
      mailersend: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
            },
          ],
        },
      },
    },
  },
});
```

```python Python highlight={8-18} theme={null}
response = client.send.message(
    message={
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "to": {
            "email": "sarah@acme-corp.com",
        },
        "providers": {
            "mailersend": {
                "override": {
                    "attachments": [
                        {
                            "filename": "billing.pdf",
                            "contentType": "application/pdf",
                            "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
                        },
                    ],
                },
            },
        },
    },
)
```

```bash cURL highlight={11-21} wrap theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "to": {
        "email": "sarah@acme-corp.com"
      },
      "providers": {
        "mailersend": {
          "override": {
            "attachments": [
              {
                "filename": "billing.pdf",
                "contentType": "application/pdf",
                "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
              }
            ]
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={8-18} theme={null}
response = courier.send_.message(
  message: {
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    to: {
      email: "sarah@acme-corp.com"
    },
    providers: {
      mailersend: {
        override: {
          attachments: [
            {
              filename: "billing.pdf",
              contentType: "application/pdf",
              data: "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
)
```

```go Go highlight={10-20} theme={null}
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{
			"mailersend": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"attachments": []any{
						map[string]any{
							"filename": "billing.pdf",
							"contentType": "application/pdf",
							"data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh",
						},
					},
				},
			},
		},
	},
})
```

```java Java highlight={6-14} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().email("sarah@acme-corp.com").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .providers(MessageProviders.builder()
            .putAdditionalProperty("mailersend", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "attachments", java.util.List.of(
                        java.util.Map.of(
                            "filename", "billing.pdf",
                            "contentType", "application/pdf",
                            "data", "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                        )
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={8-18} theme={null}
$response = $client->send->message(
  message: [
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'to' => [
      'email' => 'sarah@acme-corp.com',
    ],
    'providers' => [
      'mailersend' => [
        'override' => [
          'attachments' => [
            [
              'filename' => 'billing.pdf',
              'contentType' => 'application/pdf',
              'data' => 'Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh',
            ],
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={9-27} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "mailersend",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "attachments": [
                            {
                              "filename": "billing.pdf",
                              "contentType": "application/pdf",
                              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
                            }
                          ]
                        }
                        """
                    ),
                }
            },
        },
    },
};

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

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"email": "sarah@acme-corp.com"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.providers '{"mailersend": {"override": {"attachments": [{"filename": "billing.pdf", "contentType": "application/pdf", "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"}]}}}'
```

```text MCP theme={null}
With Courier MCP, send my template to sarah@acme-corp.com with an attachment through MailerSend.
```

## Troubleshooting

> [accordion] MailerSend 422 response code
>
> A [422 error](https://www.mailersend.com/help/how-to-start-sending-emails#rest-api) from MailerSend has several possible causes:
>
> | Error | Cause |
> | - | - |
> | From email must be verified | The domain of the from email address must match the domain that the API token is from. |
> | Must provide HTML/text or template ID | The API request is missing content; provide either an HTML/text body or a template ID. |
> | File type not supported | The attachment isn't a [supported file type](https://developers.mailersend.com/api/v1/email.html#supported-file-types). |
> | Reply-to must be a valid email | The `reply_to` parameter isn't a valid email address. |
> | Email quota reached | The account's quota has been reached. Ensure your account is approved for production sending. |
>
> The most common cause is an unverified sending domain. [Verify your domain with MailerSend](https://www.mailersend.com/help/how-to-verify-and-authenticate-a-sending-domain) before using it with Courier.

## Provider details

```text theme={null}
mailersend
```

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

> [card] [Send to a specific provider](https://www.courier.com/docs/send/send-to-a-provider.md)
>
> When that is worth doing, and what you give up: failover, channel priority, and providers you add later.

> [card] [Set a send rate limit](https://www.courier.com/docs/integrations/send-rate-limits.md)
>
> Control how fast Courier sends to this provider. Sends above the rate are queued.
