Authentication

Every request to the Envoke REST APIs is authenticated with HTTP Basic Auth: your API ID is the username and your API Key is the password. This article explains where to find them, what must be in place before they work, how API limits apply, and what the API returns when it refuses a request.

---

Credentials

Credential	Basic Auth role	Format
API ID	Username	32 hexadecimal characters
API Key	Password	32 characters, which can include /, -, _, *, and ?

The API ID and API Key belong to one Envoke account, and every request made with them reads and changes that account’s data only. If your organisation has more than one Envoke account, each account has its own API ID and API Key.

There is one API Key per account. It is not tied to an Envoke user, and anyone who has it has full API access to the account, so keep it out of source control, browser code, and shared documents. Envoke support can replace a key; there is no way to replace it yourself.

The same credentials work for every API in this reference, on both /v1 and /v2.

---

Find Your API ID and API Key

1. In Envoke, open the settings menu and choose Account settings.
2. Choose the Integrations tab.
3. In the API section, choose Reveal Credentials. The API_ID line is your API ID and the API_KEY line is your API Key.

The API section is shown only to users who can manage the API. Other users see “Only administrators can view API connection details.”

---

Before Your Key Works

All of the following must be true. Until they are, requests are refused even with the correct API ID and API Key.

• Your plan includes the API. If it does not, the Integrations tab shows an Upgrade your plan link instead of the API section.
• The API is enabled for your account. If the Integrations tab shows an Enable API button, choose it. Enabling the API sets your account’s limits to 1,000 requests a day and 3 requests a second (see API Limits) and shows the API section with your credentials. Until the API is enabled, every request returns 429 with API access is not enabled for your account.
• Your account has a current key. If the API section says “Please contact support in order to use the API” instead of offering Reveal Credentials, your account has an older key that Envoke support must replace before you can use the API.
• Your account is active. A closed or inactive account returns 403 (see Error Responses).

The Send API has one more prerequisite: the Transactional API preference on the same Integrations tab. See the Send API overview.

---

Make a Request

Pass the API ID and API Key with curl’s -u option, which sends them in an Authorization: Basic header. Keep the quotes: the key can contain characters your shell would otherwise interpret.

export API_ID="your API ID"
export API_KEY="your API Key"

curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/tags?limit=1"

Any other HTTP client works the same way: send the header Authorization: Basic followed by the Base64 encoding of API_ID:API_KEY.

A 200 response confirms that the credentials work. This request returns a JSON array holding at most one tag, or [] if your account has no tags.

---

API Limits

Every authenticated request counts towards your account’s API limits. Enabling the API sets two limits:

Limit	Default	Resets
Daily	1,000 requests	At midnight Eastern time
Per second	3 requests	At the start of each second

The Integrations tab shows your daily limit, the number of requests counted so far today, and the per-second limit. To raise a limit, or to reset the daily count early, contact Envoke support.

• What counts. Each request that passes authentication counts once, whatever its result, including requests refused with 429 because a limit was exceeded. Requests refused with 401, or with 403 because the account is not active, do not count.
• Webhook deliveries count too. Each event Envoke delivers to your webhook endpoints adds one to the same daily and per-second counts. Deliveries are never refused for being over a limit, but a high webhook volume can use up the daily limit and cause your own API requests to be refused with 429.
• Email alerts. When your account reaches 80% of its daily limit, and again when it exceeds the limit, Envoke emails the account administrator who signed in most recently. Each alert is sent at most once a day.
• No limit headers. Responses carry no rate-limit headers. Track your own request rate, or check the usage on the Integrations tab.

When a request is refused with 429 for the per-second limit, wait a second and retry. When it is refused for the daily limit, every further request is refused until midnight Eastern time, unless Envoke support resets the count or raises the limit.

---

Error Responses

401 — Invalid credentials

Returned when the Authorization header is missing, or the API ID and API Key do not match an Envoke account.

{
  "success": false,
  "result_data": [],
  "result_text": "Invalid credentials"
}

The response carries a WWW-Authenticate: Basic header. Its Content-Type is text/html, although the body is JSON.

403 — Account not active

Returned when the API ID and API Key are correct but the account cannot use the API: it has been closed, or it is cancelled or suspended. The body is one of:

{
  "success": false,
  "result_data": [],
  "result_text": "This account has been closed."
}

{
  "success": false,
  "result_data": [],
  "result_text": "This account is not active."
}

Some endpoints also return 403 for reasons of their own, such as the Reports API on an account restricted from contact-level email activity; each is documented with its endpoint, for example Contact Activity errors.

429 — API not enabled or limit exceeded

When the API has not been enabled for the account:

{
  "success": false,
  "result_data": [],
  "result_text": "API access is not enabled for your account."
}

When a limit is exceeded, result_text names the limit, result_data.exceeded is the period that was exceeded (day or second), and result_data.limits gives each of the account’s limits with its current usage:

{
  "success": false,
  "result_data": {
    "exceeded": "day",
    "limits": {
      "day": { "limit": 1000, "current_usage": 1001 },
      "second": { "limit": 3, "current_usage": 0 }
    }
  },
  "result_text": "Daily API limit of 1000 exceeded."
}

For the per-second limit, result_text is Per second API limit of 3 exceeded. and exceeded is second.

---

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.