Here's our recommendation on how to quickly get started on Waypoint's email API.

First, let's create our first template

Step 1: Create an account and workspace

Before we can do anything, we'll need to create an account and workspace. A workspace is where your team will collaborate on building templates, monitoring email activity, and more.

1. If you haven't already, create a free account.
2. Go to your Waypoint dashboard
3. Click the big '+' to add a new workspace.
4. Give the new workspace a name and click 'Create'.

Step 2: Create your first template

Next, we'll create a template. For this quickstart tutorial, we'll use a sample template as the base.

1. Within your new workspace, click on the 'Templates' link at the top.
2. Click '+ New'
3. Within the 'From samples' tab, click on the 'New comment' sample template.
4. Click on 'Untitled template' in the header to rename the template to on a more descriptive one (eg. 'New comment').

Step 3: Send a preview email

From Waypoint's template builder, make adjustments to the template and then send yourself a quick preview email.

1. Make any desired changes to the template – learn more about building templates.
2. Go to the 'General' tab on the template builder.
3. Within the 'Test this template' section, click on the 'Send test' button. This will send yourself an email with any live changes.
4. When you are happy with the changes, click 'Save' in the header to save the template.

Now let's hook it up to the API

Step 4: Create an API key

Now that the email template is setup and it's rendering correctly, let's hook it up to the API. We'll first need to head back to your settings page to create an API keys so your application can send data to Waypoint.

1. Navigate to the 'Settings' page of your workspace.
2. Scroll down to the 'API keys' section, click on '+ Add key', and then follow the directions to finish adding the key.
3. After creating the key, scroll down to the bottom of the 'Settings' page and you should now see your new API key with a Username and Password. We'll use these in a later step.

Step 5: Send your first API request

Next let's create the actual API request that passes in the variables that the template is expecting.

From the API endpoint reference, you can see that we'll be passing in the following data:

Property	Description
templateId	The id of the template you want to send.
variables	JSON data object that is passed to the template.
to	Email address of the receiver.

Within your application, following the instructions and code example below to setup and run your API request.

1. From the template builder, switch to the 'Data' tab. This is the data that this particular template is expecting in order to populate the template.
2. Copy the JSON data and paste it into the variables property on the API request within your application. Modify the data to map your dynamic data or simply adjust the hardcoded data for testing.
3. Switch to the 'General' tab in the template builder to copy the template ID at the bottom.
4. Paste the template ID into the templateId variable on the API request.
5. Set the to field to be be the email address of someone in your workspace (see trial plan limitations).
6. Copy and paste your username and password keys (from Step 3) into the auth object in your API request.
7. Run the API request.

Code examples

💡 Use Node.js? Write even less code in your codebase by using the Waypoint npm package.

Copy
const axios = require('axios');

axios({
  method: "post",
  url: "https://live.waypointapi.com/v1/email_messages",
  headers: {
    "Content-Type": "application/json"
  },
  auth: {
    username: API_KEY_USERNAME,
    password: API_KEY_PASSWORD
  },
  data: {
    "templateId": TEMPLATE_ID,
    "to": EMAIL_ADDRESS,
    "variables": {
      "comment": {
        "id": "comment_123",
        "user": {
          "displayName": "User1"
        },
        "channel": {
          "name": "Tutorial"
        },
        "message": "Hi, this is a test comment sent from the Waypoint API.",
        "thread": {
          "id": "thread_123",
          "user": {
            "displayName": "User2"
          }
        }
      }
    } 
  }
})

Copy
curl "https://live.waypointapi.com/v1/email_messages" \
  -H "Content-Type: application/json" \
  -u "API_KEY_USERNAME:API_KEY_PASSWORD"  \
  -d '{
  "templateId": "TEMPLATE_ID",
  "to": "EMAIL_ADDRESS",
  "variables": {
    "comment": {
      "id": "comment_123",
      "user": {
        "displayName": "User1"
      },
      "channel": {
        "name": "Tutorial"
      },
      "message": "Hi, this is a test comment sent from the Waypoint API.",
      "thread": {
        "id": "thread_123",
        "user": {
          "displayName": "User2"
        }
      }
    }
  }
}'

Now let's debug

Step 6. Review API request

Head to your 'Activity' page to ensure the test API request came through with the expected template data.

If successful, you should see both your preview email and your test request within your Activity events list. You can click on each item to drill down and see the full timeline of event logs along with metadata, the full email content, and template data.

Not seeing seeing anything in your activity after sending a request? View full API logs on Waypoint by clicking on the 'Troubleshoot' link on your 'Activity' page.

Still running into problems? We're happy to help – support@usewaypoint.com.

Everything look good?

Whenever you and your team are ready, we recommend the following next steps:

1. Invite your teammates to your workspace.
2. Add a custom verified domain.
3. Add approved senders.
4. Send test emails with sandbox requests (great for devs sending from local/test environments).
5. Upgrade your plan to start sending live emails (see trial plan limitations).