Send your first email

Every workspace can email you on day one. Reaching anyone else takes your own provider and your own domain.

Only need to prove the API works? The sends an email in one call with no provider setup. It reaches your signup address only, which is why this guide exists.

Prerequisites

An account with an email provider, such as SendGrid, Postmark, or Resend
A domain you can add DNS records to

Send it

Connect your own provider

Add your provider from and paste its API key. lists every one, and each page carries that provider’s credential fields.Integrations are per environment, so connect it in the same environment your API key belongs to. A provider added in Production does nothing for a Test key.

The Courier Test Email Provider stays connected alongside yours. Once you add your own, decides which one sends, so set yours first.

Verify your sending domain

Your provider has to prove it may send as you. That means DKIM and SPF records on your domain, added at your DNS host and verified in the provider’s dashboard.Skipping this is the single biggest cause of mail landing in spam. An unauthenticated message from a domain that publishes no policy is exactly what a receiving server is built to distrust. walks the records and setting the From address.

Put an email address on the profile

Email addresses a recipient by email. Nothing else is required.

await client.profiles.create("user_123", {
  profile: { email: "sarah@acme-corp.com" },
});

client.profiles.create(
    "user_123",
    profile={"email": "sarah@acme-corp.com"},
)

curl -X POST https://api.courier.com/profiles/user_123 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile": { "email": "sarah@acme-corp.com" } }'

courier.profiles.create(
  "user_123",
  profile: {email: "sarah@acme-corp.com"}
)

_, err := client.Profiles.New(context.TODO(), "user_123", courier.ProfileNewParams{
	Profile: map[string]any{"email": "sarah@acme-corp.com"},
})

ProfileCreateParams params = ProfileCreateParams.builder()
    .userId("user_123")
    .profile(ProfileCreateParams.Profile.builder()
        .putAdditionalProperty("email", JsonValue.from("sarah@acme-corp.com"))
        .build())
    .build();

client.profiles().create(params);

$client->profiles->create(
  'user_123',
  profile: ['email' => 'sarah@acme-corp.com'],
);

await client.Profiles.Create(
    "user_123",
    new()
    {
        Profile = new Dictionary<string, JsonElement>
        {
            { "email", JsonSerializer.SerializeToElement("sarah@acme-corp.com") },
        },
    }
);

courier profiles create user_123 \
  --api-key "$COURIER_API_KEY" \
  --profile '{"email": "sarah@acme-corp.com"}'

With Courier MCP, set the email sarah@acme-corp.com on user_123.

Addressing a profile rather than an address is what lets apply and what keeps one send working when the person changes their address. covers the field every other channel reads.

Send the email

Route to email and Courier picks the provider you connected.

const { requestId } = await client.send.message({
  message: {
    to: { user_id: "user_123" },
    routing: { method: "single", channels: ["email"] },
    content: { title: "Your order shipped", body: "It should arrive Thursday." },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "routing": {"method": "single", "channels": ["email"]},
        "content": {"title": "Your order shipped", "body": "It should arrive Thursday."},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "routing": { "method": "single", "channels": ["email"] },
      "content": { "title": "Your order shipped", "body": "It should arrive Thursday." }
    }
  }'

response = courier.send_.message(
  message: {
    to: {user_id: "user_123"},
    routing: {method: "single", channels: ["email"]},
    content: {title: "Your order shipped", body: "It should arrive Thursday."}
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("email")}},
		},
		Content: courier.SendMessageParamsMessageContentUnion{
			OfElementalContentSugar: &shared.ElementalContentSugarParam{
				Title: "Your order shipped",
				Body:  "It should arrive Thursday.",
			},
		},
	},
})

SendMessageParams.Message message = SendMessageParams.Message.builder()
    .to(SendMessageParams.Message.To.ofUserRecipient(
        UserRecipient.builder().userId("user_123").build()))
    .routing(SendMessageParams.Message.Routing.builder()
        .method(SendMessageParams.Message.Routing.Method.SINGLE)
        .channels(List.of(MessageRoutingChannel.ofString("email")))
        .build())
    .content(ElementalContentSugar.builder()
        .title("Your order shipped")
        .body("It should arrive Thursday.")
        .build())
    .build();

client.send().message(SendMessageParams.builder().message(message).build());

$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'routing' => ['method' => 'single', 'channels' => ['email']],
    'content' => ['title' => 'Your order shipped', 'body' => 'It should arrive Thursday.'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Routing = new() { Method = "single", Channels = ["email"] },
        Content = new ElementalContentSugar
        {
            Title = "Your order shipped",
            Body = "It should arrive Thursday.",
        },
    },
};

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

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.routing '{"method": "single", "channels": ["email"]}' \
  --message.content '{"title": "Your order shipped", "body": "It should arrive Thursday."}'

With Courier MCP, email user_123 to say their order shipped.

Email uses title as the subject line and body as the message, so both do work here. SMS ignores the title, which is why the same shorthand carries them together.

Verify

Check your email

The message arrives from the address you set on the integration.

Read the status

Open . SENT means your provider accepted it. DELIVERED means the recipient’s mail server did.

Confirm it came from your provider

Open the message and check the provider on the send event. If it says Courier Test Email Provider, channel priority is still preferring it over yours.

DELIVERED with nothing in your mail client usually means spam or a corporate gateway rather than a failed send. works that case from Logs outward.

What changes in production

A bounce is not a retry. An UNDELIVERABLE message with a BOUNCED reason means the provider rejected the recipient, and Courier does not try again. A hard bounce means the address does not exist. Suppression lists are the provider’s, not ours. After a bounce or complaint, most providers stop accepting that address. Nothing you send reaches it until you remove it there. Add a backup provider. Two email providers on the channel means an outage at one fails over rather than failing. covers the order. Unsubscribes belong in preferences. An UNSUBSCRIBED or OPT_IN_REQUIRED reason means stopped the send, which is the system working. Wire your provider’s unsubscribe webhook to them rather than keeping a second list.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Send your first email

Prerequisites

Send it

Verify

What changes in production

​Prerequisites

​Send it

​Verify

​What changes in production

Prerequisites

Send it

Verify

What changes in production