Log inCreate a free account

Language

Log inCreate a free account
Documentation menu

Calendly: add people who book

Add the people who book meetings with you on Calendly to Mailcheer: access token, webhook subscription, test booking and field mapping, step by step.

When someone books a meeting on your Calendly page, Calendly can send the booking details to a web address of your choice: that's a webhook subscription, triggered by the invitee.created event. Point it at your Mailcheer inbound webhook URL and everyone who books with you lands in your contacts.

On Calendly, webhook subscriptions are created through the API, as its help center explains. In practice, that means one token to generate in Calendly, then two commands to paste into a terminal. Every step is below.

Before you start

  • A Mailcheer inbound webhook. In Mailcheer, open Integrations → Bring in contacts and click Create an inbound webhook. Mailcheer gives you an address that looks like https://mailcheer.com/api/in/<token>. Treat it as a secret and never publish it: anyone who has it can send data to it.
  • A Calendly plan that includes webhooks. According to Calendly's help center: Professional, Standard, Standard Plus, Teams, Teams Plus and Enterprise.
  • A terminal, to paste two curl commands.

Booking a meeting with you is not the same as agreeing to your newsletter. Only bring in people who have agreed to receive your emails. Double opt-in (a confirmation email) is on by default in Mailcheer.

1. Create a personal access token

The token proves to Calendly that the commands come from you.

  1. Log in to Calendly and open the Integrations page.
  2. Select the API & Webhooks tile.
  3. Under Personal Access Tokens, click Get a token now. If you already have a token, click Generate new token under Your personal access tokens.
  4. In Create your personal access token, give it a name you'll recognize, such as "Mailcheer".
  5. Choose its scopes: users:read, webhooks:write and scheduled_events:read. A new token has no API access until its scopes are requested.
  6. Click Create Token, then Copy token.

Calendly doesn't store the token and can't show it to you again, so copy it right away and keep it like a password.

What each scope is for:

ScopeWhat it does here
users:readReads your Calendly identifiers (step 2).
webhooks:writeCreates the webhook subscription (step 3).
scheduled_events:readLets you receive the invitee.created event.

2. Find your Calendly identifiers

The subscription needs two addresses that identify you at Calendly: yours (the user) and your organization's. Replace <your Calendly token> and paste this command into a terminal:

curl --request GET \
  --url https://api.calendly.com/users/me \
  --header 'Authorization: Bearer <your Calendly token>'
  • --request GET: asks for information without changing anything.
  • --url …/users/me: the API address that describes your own account.
  • --header 'Authorization: Bearer …': your token, proving it's you.

In the response, under resource, write down two values:

  • uri: your user identifier, which looks like https://api.calendly.com/users/…;
  • current_organization: your organization identifier, which looks like https://api.calendly.com/organizations/….

3. Create the webhook subscription

Replace the four values between < >, then paste the command into the terminal:

curl --request POST \
  --url https://api.calendly.com/webhook_subscriptions \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your Calendly token>' \
  --data '{
    "url": "<your Mailcheer inbound webhook URL>",
    "events": ["invitee.created"],
    "organization": "<the current_organization value>",
    "user": "<the uri value>",
    "scope": "user"
  }'

Line by line:

  • --request POST: asks Calendly to create something.
  • --url …/webhook_subscriptions: the API address that creates webhook subscriptions.
  • Content-Type: application/json: what you send is written in JSON.
  • Authorization: Bearer …: your token, as in step 2.
  • "url": where Calendly will send each booking, meaning your Mailcheer inbound webhook URL.
  • "events": invitee.created, the "someone just booked" event.
  • "organization" and "user": the two values from step 2.
  • "scope": "user": the subscription only covers your own meetings.

If you're an owner or admin of a Calendly organization and want bookings for the whole team, change "user" to "organization" on the scope line and delete the "user" line.

Calendly replies with the new subscription. Check that state is active.

4. Make a test booking

Calendly doesn't send anything for past bookings, so you need a new one. Book a slot on your own Calendly page, using an email address you own. You can cancel that meeting afterwards.

Calendly expects a quick answer to every delivery. Mailcheer replies right away and processes the booking afterwards.

5. Map the fields in Mailcheer

Go back to your inbound webhook in Mailcheer: it shows what it received, along with the list of fields it found.

Calendly sends event (set to invitee.created), created_at, created_by and payload, which describes the person. Inside payload, Calendly's documentation puts:

  • the email address in email (full path: payload.email);
  • the full name in name;
  • the first and last name in first_name and last_name, filled in only when your event type asks for them in two separate fields (empty otherwise);
  • the answers to your booking form questions in questions_and_answers.

Then click to choose:

  • the field that holds the email (required);
  • the first name and last name, if you want them;
  • tags: fixed ones (for example calendly-booking) or taken from a field;
  • double opt-in, on by default;
  • the automation to trigger, if you have one.

To bring in people who booked before, use a file instead: see Import your contacts.

Troubleshooting

The step 3 command returns an error.

Calendly's responseWhat it means
401The token isn't recognized: check that you pasted all of it, right after the word Bearer and a space.
403 with "Please upgrade your Calendly account to Standard"Your Calendly plan doesn't include webhooks.
403 with "Insufficient scope"The token lacks the scopes it needs: create a new one with users:read, webhooks:write and scheduled_events:read.
409An identical subscription already exists.

Nothing reaches Mailcheer after a booking.

  • Check that the booking was made after you created the subscription.
  • With "scope": "user", only your own bookings are sent.
  • If deliveries keep failing for 24 hours, Calendly disables the subscription (state becomes disabled) and you have to create it again with the step 3 command. Calendly's API lets you list your subscriptions and see their state.

Sources