How to authenticate with the API

This article shows you how to send your API key with each request, and walks you through your first request to the EmailShepherd API.

Before you begin

If you don’t have an API key yet, see How to create an API key.

Send your API key with each request

Every request to the API needs two headers:

Authorization: the word Bearer, a space, then your API key.
Content-Type: application/json.

All requests go to https://api.emailshepherd.com/api/v1/.

Make your first request

Most endpoints belong to a workspace, so their URLs include a workspace ID. To find your workspace IDs, list your workspaces:

curl https://api.emailshepherd.com/api/v1/workspaces \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Replace YOUR_API_KEY with your key. The response lists each workspace with its id and name:

{
  "results": [
    { "id": 123, "name": "Marketing", ... }
  ],
  "pagination": { ... }
}

You can also find a workspace’s ID in the app: it’s the number after /workspaces/ in the address bar.

Use the ID in the URL for other endpoints. For example, this lists the projects in workspace 123, and needs the Projects: Read scope:

curl https://api.emailshepherd.com/api/v1/workspaces/123/projects \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

If a request returns 403 Forbidden, check that your key has the scope that endpoint needs. Each endpoint lists its scope in the API reference, and you can add scopes to an existing key.

Next steps

To see every endpoint and its parameters, see the API reference.