Loading...
Skip to main content

Resend

Introduction​

This step-by-step guide will walk you through sending an email notification using Courier and Resend.

Prerequisites​

You will need both Courier and Resend accounts to complete this tutorial. If you don't have accounts already, sign up before proceeding.

Related Resources

Add the Resend Integration​

Once logged in to Courier, navigate to the "Integrations" page. Click on the Resend Integration to configure it.

Courier Integrations each require different pieces of information based on the needs of the Integration provider (see the requirements for each in the "Provider Documentation" section of the sidebar to the left). In the case of Resend, we need a Resend "API Key" and a "From Address."

Resend API Key​

Once logged in to Resend, navigate to "API Keys". On this page, you can create an API key, name it, and give it appropriate permissions.

Copy your API key from Resend, and paste it into the "API Key" field on the Courier Integration page.

Resend From Address​

Next, add an email address to the "From Address" field. This will usually be an address such as noreply@mydomain.com, news@mydomain.com, or mail@mydomain.com, but any address you control is fine. Once both fields are complete, click the “Add Integration” button, then click "Save.”

Create a Notification​

Navigate to the Courier Notifications page and click “Create Notification.” Click on “Untitled Notification” to rename your notification — for this tutorial, call it “Test Appointment Reminder.” From your list of configured Integrations, click on the Resend button. Then, click the “Resend” box that has been added to the sidebar in order to bring up an email template.

You can add message blocks to the template by clicking one of the three icons on the mock-up email. The paper icon adds a text block. The hand icon adds a link. The list icon adds a repeatable list.

These text blocks can include variables using a mustache-like template syntax. Surround text with a single set of curly braces and that text will be interpreted as a variable (it will also be highlighted in green). For example, you may want to include a {name} variable (we'll cover the source of this variable data later in this tutorial).

Be sure to set the subject line for your email as well (click “New Subject” to edit it). You can also choose a different From Address — this will override the From Address in your Resend Integration settings.

Finish populating the email template with whatever text you want to send. You can also copy the example below, which contains a few variables for demonstration.

Hello {name},

This is an appointment reminder from Courier. We look forward to seeing you on {apt_date} at {apt_time}.

If you need to change your appointment for any reason, please contact us at least 24 hours in advance at {support_url} or {support_phone}.

Best regards,

Courier

When you are finished, click Publish in the upper right corner and give it a Publish Message of "Initial notification."

Send a Message​

Courier passes messages to Integrations via the Send endpoint. For this tutorial, we will send our messages with cURL, but you can use your preferred language and HTTP library. You can also use an API testing tool such as Postman or Insomnia. For additional code samples, see the "Courier API Reference".

Authorization​

Courier supports both basic and token authorization. For this tutorial, we will use token authorization. You can read more about authorization in Courier's "Authorization Overview".

We must send an Authorization header with each request. The Courier Send API also requires an event. The authorization token and event values are the "Auth Token" and "Notification ID" we see in the detail view of our “Test Appointment Reminder” event. Click the gear icon next to the Notification's name to reveal them.

As a best practice, let's assign these values to environment variables. In a Bash terminal, you can add the variables by typing VARIABLE_NAME="<value>". Some examples are provided below. Note that the values are just examples. Do not copy them — be sure to use the tokens associated with your account instead.

Courier Auth Token Variable​

COURIER_AUTH_TOKEN="YpW2yEaMDyNg6agN9yGkc9ycEg8MxiKVTiiu2WVc8"

Notification ID​

COURIER_NOTIFICATION_ID="YpW2yEaMDyNg6agN9yGkc9ycEg8"

These variables will persist for as long as your Bash session remains alive. If you quit your terminal, you will need to recreate them. However you handle your authorization tokens, keep them secure, and never add them to source control.

To verify that you created the variables correctly, you can see them by typing echo $VARIABLE_NAME. For example, typing echo $COURIER_AUTH_TOKEN will print the Courier Auth Token value to the terminal.

Building the cURL Request​

We want to send a POST request to https://api.courier.com/send. Let's build our cURL request line-by-line. First, we'll tell cURL this is a POST request.

curl --request POST

Next, add the Authorization header using the COURIER_AUTH_TOKEN variable we set earlier. We send this as a Bearer Token.

curl --request POST \
--header "Authorization: Bearer $COURIER_AUTH_TOKEN" \

We also have a Content-Type header, which is application/json.

curl --request POST \
--header "Authorization: Bearer $COURIER_AUTH_TOKEN" \
--header "Content-Type: application/json" \

We will pass the body of our request using the cURL --data option. You will often send this data in JSON format. To improve working with cURL, Courier also supports a custom urlencoded format that can be used in the place of JSON. This format allows nested data values using square bracket syntax. This guide provides examples in both formats, so feel free to use the format that you like best.

Our --data option must also contain an event and recipient. Additionally, we will send profile and data objects.

The event value, for this example, is the "Notification ID" that we assigned to our COURIER_NOTIFICATION_ID environment variable earlier.

A recipient should be a unique identifier that does not change. This prevents duplicate entries in the event that a recipient changes their email or some other identifying value. We do not have any recipients in this tutorial, so we can enter any string value. Something like “katherine_pryde” will work.

The profile information is an object that includes any key-value pairs required by our Integrations. In the case of Resend, we need an email key and value. This is the address where our message will be delivered. You can find the required keys for any Integration by selecting an Integration on the "Integrations" page. See the "Integration Provider Requirements" for details.

Lastly, we define message variables inside the data object. Remember the variables we set in the visual template editor? This is where we provide the values. Our example message had name, apt_date, apt_time, support_phone, and support_url variables. For this tutorial, we can assign example strings to each.

Our --data option should look like this:

{
  "message": {
    "template": "$COURIER_NOTIFICATION_ID",
    "to": {
      "email": "kpryde@xavierinstitute.edu"
    },
    "data": {
      "name": "Katherine Pryde",
      "apt_date": "July 31, 2019",
      "apt_time": "11:00 AM",
      "support_phone": "555-555-5555",
      "support_url": "https://courier.com/docs"
    }
  }
}

Now add the Send URL, https://api.courier.com/send, to complete the cURL request.

Complete cURL Request in both Formats​

curl --request POST \
--header "Authorization: Bearer $COURIER_AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "message": {
    "template": "'"$COURIER_NOTIFICATION_ID"'",
    "to": {
      "email": "kpryde@xavierinstitute.edu"
    },
    "data": {
      "name": "Katherine Pryde",
      "apt_date": "July 31",
      "apt_time": "11:00 AM",
      "support_phone": "555-555-5555",
      "support_url": "https://courier.com/docs"
    }
  }
}' \
https://api.courier.com/send

Before sending this request, be sure to replace the kpryde@xavierinstitute.edu value with an email address you can access. Also, note the "'"$COURIER_NOTIFICATION_ID"'" formatting in the JSON formatted --data option. The quotes are necessary to escape the JSON quotes and access the COURIER_NOTIFICATION_ID variable.

Paste your complete cURL request in either format in your terminal and hit "Return." You should receive a response like {"messageId":"<message id string>"}. You will also receive an email at the address you specified in the request body. Be sure to check your spam folder if the message doesn’t arrive in your inbox.

Congratulations, you’re on your way to crafting a better notification strategy that your audience is sure to appreciate.

Profile Requirements​

To deliver a message to a recipient over Resend, 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": "example@example.com"
    }

    // ... rest of message definition
  }
}

Sending Attachments​

To include an attachment in the email, you can use the following override:

{
  "message": {
    "template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "to": {
      "email": "example@example.com"
    },
    "data": {
      "hello": "world"
    },
    "providers": {
      "resend": {
        "override": {
          "attachments": [
            {
              "filename": "billing.pdf",
              "contentType": "application/pdf",
              "data": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgY2FuIGJhc2U2NCBkZWNvZGUh"
            }
          ]
        }
      }
    }
  }
}

Overrides (Advanced)​

You can use a provider override to replace what we send to Resend's API. Overrides are useful when a field is not yet supported by Courier or you would like to override the value that Courier generates. You can override any of the fields supported by Resend's /emails endpoint. For example, you can use Resend's Tagging with your request:

{
  "message": {
    "template": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "to": {
      "email": "example@example.com"
    },
    "providers": {
      "resend": {
        "override": {
          "body": {
            "tags": [{ "name": "environment", "value": "development" }]
          }
        }
      }
    }
  }
}