Instantly API Documentation Developer docs for Instantly.ai ## Sections • [Introduction](https://app.theneo.io/instantly-ai/instantlyapidocs/introduction.md): Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. Welcome to Instantly. Let’s get started with getting you authenticated and ready to build! 🛠️ Finding your API key 🗝️ 1 Go to Instantly Dashboard The first step to using the Instantly API platform is to find your API key. 2 Go to Settings → Integrations To get to your API key, go to your: Instantly Dashboard → Settings → Integrations → API https://app.instantly.ai/app/settings/integrations 3 Retrieve your API key The API key helps authenticate your incoming requests and is unique per Instantly workspace. You need to be on the Hypergrowth plan (or above) to be able to access the API key. • [Test your API key](https://app.theneo.io/instantly-ai/instantlyapidocs/introduction/test-your-api-key.md): Once you have your API key, send a GET request to ensure everything is ready. • [Rate limits](https://app.theneo.io/instantly-ai/instantlyapidocs/introduction/rate-limits.md): Our platform allows a maximum of 10 requests per second to prevent abuse. Going above this limit will return an error for all request types ( POST / GET ) Need help getting started or have a question? Feel free to reach support through the in-app chat 🙂 • [Campaign](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1.md): The campaign endpoints allow you to interact with individual email campaigns, update their options, sending accounts, and status. See below for details. Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. • [List campaigns](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/list-campaigns.md): The "List campaigns" section allows users to retrieve a list of campaigns associated with their account. Users can view details such as campaign IDs and names, enabling them to manage and track their marketing efforts effectively. Pagination options are available for handling large sets of campaign data. • [Get campaign name](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/get-campaign-name.md): The "Get campaign name" section allows users to retrieve the name of a specific campaign by providing the campaign ID. This feature is helpful for accessing campaign details and integrating them into external systems or applications. By utilizing this functionality, users can easily access and display campaign names without the need for manual input. • [Get campaign status](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/get-campaign-status.md): This section allows users to retrieve the status of a specific campaign using its ID. By accessing this information, users can track the progress and performance of their campaigns without the need to navigate through multiple screens or interfaces. This feature streamlines the monitoring process and provides quick access to essential campaign status data. • [Set campaign name](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/set-campaign-name.md): This section allows users to set a new name for their campaign. By providing the campaign ID and the desired name, users can easily update the name of their campaign. This feature simplifies the process of managing and organizing campaigns within the platform. • [Get campaign accounts](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/get-campaign-accounts.md): Get the list of sending accounts associated with a campaign • [Set campaign accounts](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/set-campaign-accounts.md): This endpoint sets the campaign's sending accounts to emails in the account_list . To add or remove a single sending account, skip to the next section. • [Add sending account to campaign](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/add-sending-account-to-campaign.md): This endpoint helps add a single sending account to the specified campaign. • [Remove sending account from campaign](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/remove-sending-account-from-campaign.md): This endpoint helps remove a single sending account from the specified campaign. • [Set campaign schedule](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/set-campaign-schedule.md): This endpoint helps you set one or more schedules for your campaign. Need help? Feel free to reach support through the in-app chat 🙂 • [Launch campaign](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/launch-campaign.md): The Launch campaign section allows users to initiate the launch of a campaign within the system. By providing the necessary parameters, such as the API key and campaign ID, users can trigger the campaign launch process seamlessly. The response will indicate the status of the launch operation, ensuring visibility and clarity on the campaign's progress. • [Pause campaign](https://app.theneo.io/instantly-ai/instantlyapidocs/campaign-1/pause-campaign.md): The "Pause campaign" section allows users to temporarily halt a specific campaign within their account. By pausing a campaign, users can prevent it from being actively displayed or executed, providing control and flexibility in managing their marketing efforts. This functionality helps users optimize their campaigns by allowing them to make adjustments or assess performance before resuming activity. • [Analytics](https://app.theneo.io/instantly-ai/instantlyapidocs/analytics.md): The campaign endpoints allow you to interact with individual email campaigns, update their options, sending accounts, and status. See below for details. Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. • [Get campaign summary](https://app.theneo.io/instantly-ai/instantlyapidocs/analytics/get-campaign-summary.md): Get the lead status summary for a given campaign • [Get campaign count](https://app.theneo.io/instantly-ai/instantlyapidocs/analytics/get-campaign-count.md): Get the actual data count for a campaign. Given that this endpoint counts the actual occurrences, it will also consider the numbers for any deleted leads. • [Lead](https://app.theneo.io/instantly-ai/instantlyapidocs/lead.md): The lead endpoints allow you to interact with lead data in your workspace. Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. • [Add leads to a campaign](https://app.theneo.io/instantly-ai/instantlyapidocs/lead/add-leads-to-a-campaign.md): Send a list of lead objects to add to a campaign. A maximum of 500 leads could be uploaded at the same time Only the email field is required • [Get or search for lead](https://app.theneo.io/instantly-ai/instantlyapidocs/lead/get-or-search-for-lead.md): This endpoint can also be used to search for a lead - if campaign_id is left blank, all leads matching email will be returned. • [Delete leads from a campaign](https://app.theneo.io/instantly-ai/instantlyapidocs/lead/delete-leads-from-a-campaign.md): This section allows users to delete specific leads from a campaign. Users can remove leads by providing the campaign ID and other optional parameters, such as deleting leads with matching domains. The action helps users efficiently manage their campaign's lead database by removing unwanted entries. • [Update lead status](https://app.theneo.io/instantly-ai/instantlyapidocs/lead/update-lead-status.md): Possible values for new status Basic types Active Completed Unsubscribed Additional types Setting the status to one of these values will also mark the sequence as ‘Completed’ for the lead. Interested Meeting Booked Meeting Completed Closed Out of Office Not Interested Wrong Person You can similarly send the label text if you'd like to apply custom labels. For example, if you have a custom label called “My Label,” you can simply set the new_status parameter to “My Label”. Please note that this is case-insensitive so it will have the same effect if you send “my label” (instead of “My Label”) . • [Lead Variable | Update](https://app.theneo.io/instantly-ai/instantlyapidocs/lead/lead-variable-or-update.md): When using this endpoint, all keys appearing in the variables property must already exist in the lead's data. If you'd like add a new variable, skip to the next section. • [Lead Variable | Set](https://app.theneo.io/instantly-ai/instantlyapidocs/lead/lead-variable-or-set.md): The Lead Variable | Set section allows users to update and set custom variables for a lead within a specific campaign. By providing the email address of the lead and the desired variables, users can customize and enhance their lead data for targeted marketing efforts. This functionality enables users to dynamically adjust and personalize lead information to better engage with potential customers. • [Lead Variable | Delete](https://app.theneo.io/instantly-ai/instantlyapidocs/lead/lead-variable-delete.md): Use this endpoint to remove attributes (variables) from a lead. Set variables as a list of attributes you want to remove. • [Blocklist](https://app.theneo.io/instantly-ai/instantlyapidocs/blocklist.md): The blocklist endpoints allow you to interact with your campaign blocklist. See below for details. Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. • [Add entries to blocklist](https://app.theneo.io/instantly-ai/instantlyapidocs/blocklist/add-entries-to-blocklist.md): The "Add entries to blocklist" section allows users to add email addresses or domains to a blocklist, preventing them from accessing certain services. With this functionality, users can effectively manage and control access to their platform by specifying which entries should be blocked. This action helps enhance security and streamline user management processes. • [Remove entries from blocklist](https://app.theneo.io/instantly-ai/instantlyapidocs/blocklist/remove-entries-from-blocklist.md): This api allows users to remove specific entries from the blocklist associated with their API key. By utilizing this functionality, users can efficiently manage their blocklist by selectively deleting unwanted entries. This action helps maintain the accuracy and relevance of the blocklist for their API integration. • [Account](https://app.theneo.io/instantly-ai/instantlyapidocs/account.md): The account endpoints allow you to interact with your sending accounts. See below for details. Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. • [List accounts](https://app.theneo.io/instantly-ai/instantlyapidocs/account/list-accounts.md) • [Check account vitals](https://app.theneo.io/instantly-ai/instantlyapidocs/account/check-account-vitals.md): This endpoint allows you to quickly check if the MX, SPF, DKIM, and DMARC records have been properly set for a list of domains. • [Get account status](https://app.theneo.io/instantly-ai/instantlyapidocs/account/get-account-status.md) • [Enable warmup](https://app.theneo.io/instantly-ai/instantlyapidocs/account/enable-warmup.md): This API allows users to update the warmup status for a specific email address associated with their API key. By enabling warmup, users can ensure that the designated email address is prepared for receiving and processing incoming data effectively. This feature helps optimize the performance and reliability of email-related operations within the application. • [Pause warmup](https://app.theneo.io/instantly-ai/instantlyapidocs/account/pause-warmup.md): The "Pause warmup" section allows users to temporarily halt the warmup process for an account. By utilizing this functionality, users can manage the warmup status of their email addresses effectively. This feature provides control over the warmup process, allowing users to pause it as needed. • [Mark accounts as fixed](https://app.theneo.io/instantly-ai/instantlyapidocs/account/mark-accounts-as-fixed.md): To mark all accounts as fixed, skip the email parameter in the request body. • [Delete account](https://app.theneo.io/instantly-ai/instantlyapidocs/account/delete-account.md): This API endpoint allows users to permanently remove an account from the system. By utilizing this functionality, users can securely delete unwanted accounts and associated data. This action is irreversible, ensuring that accounts are removed from the system effectively. • [Updating Custom Tracking Domain](https://app.theneo.io/instantly-ai/instantlyapidocs/account/updating-custom-tracking-domain.md): See the “ Custom Tracking Domain ” section for details on how to add, update, and remove custom tracking domains for sending accounts. https://developer.instantly.ai/custom-tracking-domain • [Unibox](https://app.theneo.io/instantly-ai/instantlyapidocs/unibox.md): The account endpoints allow you to interact with the Instantly Unibox. See below for details. Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. • [Emails | List](https://app.theneo.io/instantly-ai/instantlyapidocs/unibox/emails-or-list.md): Note: The body of the email object is only sent when you have preview_only=false (i.e., the default state is to send the content preview only). The body object may have a property called text and/or html, depending on the original content of the email. The email_type parameter now accepts a new value manual . When applied, it will return the following email types: Sent manually through the Unibox Received emails (responses from leads) Emails scheduled to be sent (from the Unibox) • [Emails | Count Unread](https://app.theneo.io/instantly-ai/instantlyapidocs/unibox/emails-or-count-unread.md): Get the number of unread emails in the “Primary” box. • [Threads | Mark as read](https://app.theneo.io/instantly-ai/instantlyapidocs/unibox/threads-or-mark-as-read.md): This endpoint marks all emails in a thread as read. The thread id should be passed in the URL and not the POST body (see example code). • [Send Reply](https://app.theneo.io/instantly-ai/instantlyapidocs/unibox/send-reply.md): Send an email reply through Unibox • [More coming soon](https://app.theneo.io/instantly-ai/instantlyapidocs/unibox/more-coming-soon.md): The Unibox API docs are currently being tested and deployed; we'll add more sections soon. For early access, please contact support. • [Tags](https://app.theneo.io/instantly-ai/instantlyapidocs/tags.md): Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. The custom tag endpoints are a set of endpoints that allow you to manage custom tags and associate them with specific resources. Custom tags are labels or categories that you can assign to different entities, such as user accounts or campaigns, to organize and group them based on certain criteria. Resource Type and Resource ID: The resource type and resource ID are used to uniquely identify a specific resource. Resource Type : The resource type is a way to categorize different types of resources in your application. It helps distinguish between different entities that can have custom tags assigned to them. For example, you might have resource types such as " account " for user accounts and " campaign " for marketing campaigns. Resource ID : The resource ID is a unique identifier for a specific resource within a resource type. It allows you to reference a particular resource when assigning or retrieving custom tags. For example, if you have a user account with an email address " johndoe@instantly.ai ", the email address would be the resource ID for the " account " resource type. • [Create a new Tag](https://app.theneo.io/instantly-ai/instantlyapidocs/tags/create-a-new-tag.md): Create a new custom tag and assign it to specified resources if resource_ids and resource_type are provided. For resource_type 1 ( ACCOUNT ), only email addresses are accepted. For resource_type 2 ( CAMPAIGN ), only UUIDs are accepted. Please ensure your input matches the corresponding format based on the resource_type specified. Heads up! if you are still unsure about what resource_type to use, you should check this guide first • [Get a Tag by id](https://app.theneo.io/instantly-ai/instantlyapidocs/tags/get-a-tag-by-id.md): Retrieve information about a specific custom tag. • [List Tags](https://app.theneo.io/instantly-ai/instantlyapidocs/tags/list-tags.md): Retrieve a list of all custom tags available in your organization, optionally filtered by certain criteria. • [Update Tag](https://app.theneo.io/instantly-ai/instantlyapidocs/tags/update-tag.md): Update an existing custom tag by modifying the label or description. Use the Update Tag endpoint to modify only the label or description, if you want to assign or unassign resources use this endpoint instead • [Delete a Tag](https://app.theneo.io/instantly-ai/instantlyapidocs/tags/delete-a-tag.md): Delete an existing custom tag. We cannot recover your tag after you delete it. • [Assign or unassign a tag](https://app.theneo.io/instantly-ai/instantlyapidocs/tags/assign-or-unassign-a-tag.md): Toggle the assignment status of one or more custom tags for specific resources, either assigning or unassigning the custom tags as required. For resource_type 1 ( ACCOUNT ), only email addresses are accepted. For resource_type 2 ( CAMPAIGN ), only UUIDs are accepted. Please ensure your input matches the corresponding format based on the resource_type specified. Heads up! if you are still unsure about what resource_type to use, you should check this guide first • [Email Verification](https://app.theneo.io/instantly-ai/instantlyapidocs/email-verification.md): Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. The Verification endpoints allow you to verify emails, including those behind catch-all domains. See below for details. There are currently two categories of verification endpoints. Submitting a verification job Checking the status of a verification job • [Verify single email](https://app.theneo.io/instantly-ai/instantlyapidocs/email-verification/verify-single-email.md): This endpoint helps verify a single email address. If an email takes longer than 10 seconds to verify, the endpoint will return the status as “pending”. In that case, you may use the /verify/single/status to check the status of the verification job. Alternatively, you can send a webhook_url to receive the results instead of polling the status endpoint. • [Get single email verification result](https://app.theneo.io/instantly-ai/instantlyapidocs/email-verification/get-single-email-verification-result.md): Get the verification result for single email verification. This endpoint can be used if the /verify/single endpoint takes longer to verify emails, which can happen for certain tricky emails/domains. The result will be available for one day after verification. Alternatively, you can send a webhook_url to the /verify/single endpoint to receive the results instead of polling the /status endpoint. • [Custom Tracking Domain](https://app.theneo.io/instantly-ai/instantlyapidocs/custom-tracking-domain.md): The Custom Tracking Domain endpoints allow you to add, remove, or check status of custom tracking domains that are used for tracking campaign metrics such as opens, link clicks, etc. Help article: https://help.instantly.ai/en/articles/6984188-custom-tracking-domain Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version. • [Add a custom tracking domain](https://app.theneo.io/instantly-ai/instantlyapidocs/custom-tracking-domain/add-a-custom-tracking-domain.md): This endpoint helps add a new custom tracking domain for a specific sending account. Please make sure you have updated the CNAME record for the host - read more here: https://help.instantly.ai/en/articles/6984188-custom-tracking-domain • [Get status of tracking domain host](https://app.theneo.io/instantly-ai/instantlyapidocs/custom-tracking-domain/get-status-of-tracking-domain-host.md): Get the current status of a tracking domain host. This endpoint can be used to check whether the CNAME and SSL for a tracking domain are set up as expected. • [Remove tracking domain](https://app.theneo.io/instantly-ai/instantlyapidocs/custom-tracking-domain/remove-tracking-domain.md): This endpoint helps you remove a custom tracking domain for a specific sending account.