n8n Integration

Heymarket integrates with n8n to help you automate workflows across the business applications you already use. You can send Heymarket messages when events occur in other systems, or trigger automated workflows when activity occurs in Heymarket.

The integration supports a range of triggers and actions for messages, contacts, conversations, calls, and lists.

Triggers

Triggers start an n8n workflow when a specific event occurs in Heymarket.

• Message Received — Triggers when a contact sends a message to one of your inboxes.
• Message Sent — Triggers when a team member sends a message from one of your inboxes. Messages sent through integrations, including n8n, do not trigger this event.
• Chat Started (Inbound) — Triggers when a contact starts a new conversation.
• Chat Started (Outbound) — Triggers when a team member starts a new conversation.
• Opt-Out Received — Triggers when a contact responds with an opt-out keyword.
• Incoming Call — Triggers when an inbound phone call is received.
• Contact Updated — Triggers when a contact is created or updated. This event applies to the entire Heymarket account rather than a specific inbox.

Actions

Actions allow an n8n workflow to perform operations in Heymarket.

• Send Message — Sends a message using the text provided in the workflow.
• Send Template Message — Sends a message using a saved Heymarket template.
• Create or Update Contact — Creates a new contact or updates an existing contact when the phone number already exists. Custom contact fields can also be updated as part of the same operation.
• Create List — Creates a new list, optionally including members.
• Add Contact to List — Adds a contact to an existing list.
• Remove Contact from List — Removes a contact from an existing list.

Generating Your n8n API Key

Step 1

Sign in to Heymarket Web and navigate to:

Settings → Manage Integrations → n8n

Step 2

Click Generate Key.

You must be an Owner or Admin of the team to generate an n8n API key.

Step 3

Copy the API key immediately and store it securely.

The key is displayed only once and cannot be viewed again after leaving the page.

Important: Your Zapier API key cannot be used with n8n, and your n8n API key cannot be used with Zapier. These integrations use separate credentials so either integration can be disabled without affecting the other.

Important: Generating a new n8n API key immediately invalidates the previous key. Any n8n credentials using the old key will stop working until they are updated with the new key. Revoking a key also takes effect immediately.

Setting Up Heymarket Triggers

Step 1

In n8n, create a new credential

Step 2

Under Credential, select new credential and enter your Heymarket n8n API key.

Save the credential and use the Test button to verify that the key is valid.

Leave the Base URL unchanged unless Heymarket Support instructs you to modify it.

Step 3

Select the new workflow and the Event that should trigger your workflow.

Step 4

Select the inboxes you want to monitor.

All inboxes associated with your Heymarket team will be available for selection, including inboxes you are not personally a member of. This is because the n8n API key is associated with the team, rather than an individual user.

The Contact Updated event applies to the entire account and therefore does not require an inbox selection.

Step 5

Add the remaining workflow steps that should run after the trigger.

Once your workflow is ready, activate it.

Heymarket automatically registers the event subscription when the workflow is activated and removes the subscription when the workflow is deactivated.

Setting Up Heymarket Actions

Step 1

In n8n, start a workflow using the trigger application of your choice.

Step 2

Add the Heymarket node as a subsequent step in the workflow.

Step 3

Under Credential, select the Heymarket credential you created earlier, or create a new credential using your Heymarket n8n API key.

Step 4

Select the appropriate Resource:

• Message
• Contact
• List

Then select the Operation you want to perform.

Step 5

Configure the fields required for the selected operation.

Phone numbers must be US or Canada numbers. Formatting is flexible — spaces, dashes, parentheses and a leading plus are all removed before the number is checked. These are equivalent:

+1 500-555-0001

15005550001

5005550001

A 10-digit number is assumed to be US or Canada and the country code is added for you. Short codes of 4 to 6 digits are also accepted.

Numbers outside the US and Canada are not currently supported and will fail with invalid_phone_number.

For Send Template Message, select the required Heymarket template and provide any values required by that template.

Step 6

Activate the workflow.

Your Heymarket action is now ready to run as part of the n8n workflow.

Opt-Out Handling

Heymarket automatically honors contact opt-outs.

If you attempt to send a message to a contact who has opted out of messages from the selected inbox, the n8n action will fail with an error indicating that the contact has opted out.

No message will be sent in this situation.

Error Handling and Retries

Every failed action returns an error code.

Most errors indicate that the request cannot succeed without being corrected, so n8n marks the item as failed and moves on.

Two errors have different retry behavior:

• rate_limited — n8n pauses and retries after a delay.
• internal_error — n8n automatically retries the request.

All other errors fail immediately and are not automatically retried.

Credential Errors

• missing_api_key — 401
  • No API key was provided.
  • Resolution: Re-select the Heymarket credential on the node.
• invalid_api_key — 401
  • The API key is invalid, was revoked, or was replaced when a new key was generated.
  • Resolution: Generate a new API key in Heymarket and update the n8n credential.

Invalid Request Errors

• invalid_request — 400
  • A required field is missing or malformed.
  • Resolution: Check the field values configured on the node.
• invalid_phone_number — 400
  • The phone number is not a valid US or Canada number.
  • Resolution: See the phone number requirements above.
• invalid_email — 400
  • The email address is invalid.
  • Resolution: Provide a valid email address.
• message_content_required — 400
  • Neither message text nor a template was provided.
  • Resolution: Provide either message content or a template.
• unknown_event — 400
  • The specified trigger event is not recognized.
  • Resolution: Select one of the available events from the Event list.
• invalid_hook_url — 400
  • Heymarket could not reach your n8n webhook URL.
  • Resolution: See the troubleshooting section below.

Resource Not Found

• inbox_not_found — 404
  • The inbox no longer exists or belongs to another account.
  • Resolution: Re-select the inbox.
• list_not_found — 404
  • The list no longer exists.
  • Resolution: Re-select the list.
• template_not_found — 404
  • The template was deleted or renamed.
  • Resolution: Re-select the template.
• contact_not_found — 404
  • No contact matches the specified phone number.
• hook_not_found — 404
  • The event subscription no longer exists.
  • Resolution: Deactivate and reactivate the workflow to recreate the subscription.

Request Rejected

• unsubscribed_number — 409
  • The contact has opted out of messages from the selected inbox.
  • No message was sent.
  • The contact must opt back in before messages can be sent from that inbox.
• send_not_allowed — 409
  • The account is not currently permitted to send messages from the selected inbox.
  • Resolution: Contact Heymarket Support.
• no_sender_available — 409
  • No user could be resolved to send the message.
  • Resolution: Ensure that the inbox has at least one active member.
• list_size_exceeded — 409
  • The list has reached its maximum allowed size.

Rate Limits and Internal Errors

• rate_limited — 429
  • The account has reached its sending limit or is subject to a lower trial limit.
  • n8n automatically waits and retries after a delay.
• internal_error — 500
  • An unexpected error occurred on the Heymarket side.
  • n8n automatically retries the request. If the problem persists, contact Heymarket Support.

Limits

Request Size

Each request can be up to 256 KB.

Sending a very large batch of list members in a single step may exceed this limit. If necessary, split the operation across multiple steps.

List Size

Lists have a maximum size. Attempting to exceed the limit returns:

list_size_exceeded

Dropdown Limits

The Inbox, List, Template, and Contact Field dropdowns display up to 500 entries.

If your account contains more than 500 entries of any of these types, the dropdown may not display the entry you need.

If the required entry is not listed, use an n8n expression to provide its ID directly.

Troubleshooting

The Credential Test Button Fails

The API key may be invalid or revoked.

Generate a new API key in Heymarket and enter it again.

Remember that generating a new API key immediately invalidates the previous key. Any other n8n credential using the old key must also be updated.

Activating a Workflow Fails with invalid_hook_url

Heymarket must be able to reach your n8n instance over the public internet to deliver trigger events.

Activation can fail if your n8n instance is:

• Self-hosted behind a firewall or VPN
• Accessible only through a private network or local address
• Not served over HTTPS
• Otherwise unreachable from the public internet

n8n Cloud works without additional configuration.

For a self-hosted n8n instance, the webhook URL must be publicly reachable over HTTPS.

A Trigger Worked Before but Has Now Stopped

If Heymarket repeatedly cannot deliver events to your webhook URL, the event subscription is removed so events are not queued indefinitely.

This can happen if your n8n instance was:

• Temporarily unavailable
• Moved to a different URL
• Made inaccessible from the public internet

Once the instance is reachable again, deactivate and reactivate the workflow to register the subscription again.

A Message Was Not Delivered and No Error Appeared

Check whether the contact has opted out.

Opt-outs are per inbox, so a contact may be able to receive messages from one inbox but not another.

The Workflow Is Sending Duplicate Messages

Check whether the workflow is triggered by Message Sent.

Messages sent through n8n do not trigger the Message Sent event. However, messages sent by Heymarket Automations do trigger this event.

If both an Automation and an n8n workflow respond to the same activity, they may create a loop that results in duplicate messages.