Calendly

Your event types, scheduled events and their invitees — to send a booking link or react to a booking.

A Calendly connection lets the Calendly node list your event types with their booking links, list and read scheduled events with their invitees, and cancel an event. The typical use is answering an email with a booking link.

The connection holds a Calendly personal access token. It is encrypted at rest, applied by the server at call time, and never appears in a workflow.

At a glance

• Identifier: calendly
• Family: Service
• Set up by: A member (personal) or an administrator (shared with the organisation)
• Authentication: API key or token
• Credential type: service:calendly
• Official API documentation: https://developer.calendly.com/api-docs
• API base URL: https://api.calendly.com
• Rate limit applied by Mankomail: 60 requests per minute and per connection; up to 3 attempts on a 429 or a 5xx
• Connection test: Yes

Step by step

The same steps are shown in the connection form of the app.

1. Open Calendly, then “Integrations & apps” → “API & webhooks”.
2. Under “Personal access tokens”, click “Generate new token” and give it a name.
3. Copy the token shown and paste it below: Calendly will never show it again.

Connection fields

Field	Kind	Required	Notes
Personal access token (token)	Secret — never shown again	Yes	It grants access to your Calendly account with your own permissions.

Before you start

• The token is created by the Calendly user whose calendar the workflows will use, from Integrations & apps → API & webhooks.
• The token acts with that user’s own permissions. Every list is scoped to that user: List my event types returns the event types of the account that owns the token, not those of the whole organisation.
• Each person who wants their own event types in a workflow creates their own token and their own connection.

Permissions

A Calendly personal access token has no scope to tick in Mankomail: the connection can do what the account can do. The node uses it for:

Action	Calendly endpoint
Get my account	GET /users/me — also returns the account’s booking URL.
List my event types	GET /users/me, then GET /event_types for that user. Only active event types are listed.
List scheduled events	GET /users/me, then GET /scheduled_events for that user, filterable by status, period and event type.
Get one scheduled event	The event and, with Include invitees, its invitees.
Cancel a scheduled event	Cancels the event with the Cancellation reason. This is the only action that changes something in Calendly.

Add the connection

1. Open Connections. In the Third-party services section, find the Calendly card and click Connect.
2. Give the connection a Name — for example the person’s name — and choose the Scope: Personal (only you can see and use it) or Organisation (the whole organisation uses it; only an administrator can create one).
3. Paste the token and click Create the connection.
4. Back in the list, click Configure on the new connection, then Test the connection.

The test calls GET /users/me. When the token is valid it shows The connection works followed by the account’s name (or email). A refused token fails with “the service rejects the key”.

In a node, pick the connection in Calendly connection. The Event type picker lists the active event types of that account, with their duration to tell two homonyms apart. It also accepts an event type API URI pasted as is (https://api.calendly.com/event_types/…); a public booking page URL (https://calendly.com/name/30min) is not accepted, because it does not contain the API identifier.

To replace the token, open Configure, paste the new value and save; a secret field left empty keeps the current value. Delete is refused while a published workflow uses the connection.

Webhooks

Mankomail has no dedicated Calendly trigger.

To start a workflow on a Calendly booking, use the generic Webhook received trigger and declare its URL (<PUBLIC_BASE_URL>/hooks/wf/<token>) as a webhook subscription in Calendly. In that case the URL token is the only proof of origin: the Calendly-Webhook-Signature header is not checked by the generic trigger, and the body arrives under data.webhook.

Common errors

Message or code	Cause	What to do
Test: “the service rejects the key” (integration.unauthorized)	Token revoked or mistyped.	Generate a new token in Calendly and replace it in Configure.
Test: “the service quota is exceeded” (integration.rate_limited)	Calendly answered 429.	The token is fine: try again in a moment.
Test: “the service did not answer” (integration.unavailable)	Network failure or Calendly outage.	Try again.
integration.unauthorized during a run	401 or 403.	Replace the token. Retrying will not help.
integration.not_found	404: the event type or scheduled event URI does not exist for this account.	Check the URI and the connection chosen.
integration.rejected	400 or 422: Calendly refused the request (for example cancelling an event that is already cancelled, or an invalid period).	Fix the node settings.
integration.rate_limited	429 after retries. Mankomail sends at most 60 requests per minute per connection (the limit of Calendly’s lowest plans) and retries up to 3 times, honouring Retry-After.	Transient: the engine resumes the step later.
integration.unavailable	5xx, 409 or network failure, after retries.	Transient: the engine resumes the step later.
integration.connection_unusable	The connection was deleted, is not active, is out of your scope, or belongs to another service.	Pick a valid connection in the node.

Nodes that use this connection

• Calendly — calendly.api