/iCxdZddlZddlZddlmZmZmZmZddlZeje Z dZ Gdde ZGddZd efd Ze d k(rddlZej$ej& eZeej,d krBededededededej0dej,dZedk(r-ej5dZeej8ed yedk(rheej,dkredej0dej;ej,d Zeej8ed yedk(r-ej=dZeej8ed yedk(rieej,dkredej0dej?ej,d Zeej8ed yedeej0dyy) z Instantly.ai API V2 Client ========================== Python wrapper for the Instantly.ai cold email platform API V2. API Docs: https://developer.instantly.ai/api/v2 Auth: Bearer token Base URL: https://api.instantly.ai/api/v2 Created: 2026-02-17 N)AnyDictListOptionalzhttps://api.instantly.ai/api/v2c2eZdZdZddededeffd ZxZS)InstantlyAPIErrorz/Raised when the Instantly API returns an error. status_codemessage response_bodycZ||_||_||_t|d|d|y)NzInstantly API Error : )r r r super__init__)selfr r r __class__s ./mnt/e/genesis-system/core/instantly_client.pyrzInstantlyAPIError.__init__s5& * / }BwiHI)N) __name__ __module__ __qualname____doc__intstrrr __classcell__)rs@rrrs*9JCJ#JcJJrrceZdZdZd2dedefdZ d3dededeed eed eed e f d Z d4d edeedeedeed ef dZ ded efdZ d5dedee edeed efdZded efdZded efdZded efdZded efdZ d6dedeedeedeedeed eed!eed"eed#eed$eeee fd efd%Z d7d&e edeedeed'ed(ed ef d)Z d8deedeed edeedeed ef d*Zd+ed efd,Zd+ed efd-Zd+ed efd.Z d9deed+eed ed efd/Zd:d ed efd0Zded efd1Zy);InstantlyClientz Client for the Instantly.ai API V2. Usage: client = InstantlyClient(api_key="your_api_key_here") campaigns = client.list_campaigns() client.create_lead(campaign_id="...", email="...", first_name="...") api_keytimeoutc||_||_tj|_|jj j d|dddy)z Initialize the Instantly API client. Args: api_key: Instantly API V2 key (Bearer token) timeout: Request timeout in seconds zBearer zapplication/json) Authorizationz Content-TypeAcceptN)rrrequestsSessionsessionheadersupdate)rrrs rrzInstantlyClient.__init__-sO  '')  ##&wi0.(%  rNmethodendpointparams json_data extra_timeoutreturnc t|}|xs |j}tjd|d||r-tjdt j |d |j j|||||}|jjd} |jjd} | tjd| d| d|jdk\rn |j } | } t'| t(r+| jd| jdt+| } t|jt+| | |jdk(s|j$j-sd|jdS |j S#tjj$rtdd|d |d tjj$r} td d |d | d} ~ wwxYw#tj t"f$r|j$} Y4wxYw#tj t"f$r|j$|jdcYSwxYw)a Make a request to the Instantly API. Args: method: HTTP method (GET, POST, PATCH, DELETE) endpoint: API endpoint path (e.g., "/campaigns") params: Query parameters json_data: JSON request body extra_timeout: Override default timeout Returns: Parsed JSON response Raises: InstantlyAPIError: If the API returns an error zInstantly API  z Body: indent)r'urlr)jsonriz Request to z timed out after srzConnection error to r NzX-RateLimit-RemainingzX-RateLimit-Limitz Rate limit: /z remainingir errorsuccess)statusr )raw_textr )BASE_URLrloggerdebugr3dumpsr$requestr" exceptionsTimeoutrConnectionErrorr%getr JSONDecodeError ValueErrortext isinstancedictrstrip)rr'r(r)r*r+r2rresponseerate_remaining rate_limit error_body error_msgs r_requestzInstantlyClient._request>sI0 8*%/4<< ~fXQse45  LL8DJJy$C#DE F J||++ ,H"))--.EF%%))*=>  % LL>.)9:,jQ R   3 & +%]]_ #I*d+&NN9jnnWcR\o6^_ #H$8$8#i.*U U   3 &hmm.A.A.C'8L8LM M T==? "9""** Y#C;se;LWIUV)WX X""22 J#A)=cU"QC'HI I J((*5 +%]]  +$$j1 T ( h>R>RS S Ts=& F *HH2 A H,G>>H%H/.H/22I'&I'limitr9searchstarting_afterc\d|i}|||d<|r||d<|r||d<|jdd|S)a| List campaigns. GET /campaigns Args: limit: Number of campaigns to return (default 10) status: Filter by status (0=draft, 1=active, 2=paused, 3=completed) search: Search campaigns by name starting_after: Pagination cursor Returns: Dict with campaigns list and pagination info rQr9rRrSGET /campaignsr)rP)rrQr9rRrSr)s rlist_campaignszInstantlyClient.list_campaignssN*5!  %F8  %F8  '5F# $}}UL}@@r campaign_idc,|jdd|S)z Get a specific campaign by ID. GET /campaigns/{id} Args: campaign_id: The campaign UUID Returns: Campaign details dict rU /campaigns/rXrrZs r get_campaignzInstantlyClient.get_campaigns}}Uk+$?@@rname sequencescampaign_schedulecNd|i}|r||d<|r||d<|jdd|S)a+ Create a new campaign. POST /campaigns Args: name: Campaign name sequences: List of sequence objects with steps and variants. Only the first element is used. Format: [{"steps": [{"type": "email", "delay": 0, "variants": [{"subject": "...", "body": "..."}]}]}] campaign_schedule: Schedule config with timezone, start_date, end_date, schedules Returns: Created campaign dict with id r_r`raPOSTrVr*rX)rr_r`rabodys rcreate_campaignzInstantlyClient.create_campaigns=,!'~  )D  (9D$ %}}V\T}BBrc 0|jdd||S)z Update a campaign. PATCH /campaigns/{id} Args: campaign_id: Campaign UUID **kwargs: Fields to update (name, sequences, campaign_schedule, etc.) Returns: Updated campaign dict PATCHr\rdrX)rrZkwargss rupdate_campaignzInstantlyClient.update_campaigns }}W K=&AV}TTrc2|jdd|diS)z Activate (start) a campaign. POST /campaigns/{id}/activate Args: campaign_id: Campaign UUID Returns: Activation result rcr\z /activaterdrXr]s ractivate_campaignz!InstantlyClient.activate_campaigns#}}V{;-y%IUW}XXrc2|jdd|diS)z Pause a campaign. POST /campaigns/{id}/pause Args: campaign_id: Campaign UUID Returns: Pause result rcr\z/pauserdrXr]s rpause_campaignzInstantlyClient.pause_campaigns#}}V{;-v%FRT}UUrc,|jdd|S)z Delete a campaign. WARNING: This is permanent. DELETE /campaigns/{id} Args: campaign_id: Campaign UUID Returns: Deletion result DELETEr\rXr]s rdelete_campaignzInstantlyClient.delete_campaigns}}X'BCCremaillist_id first_name last_name company_namewebsitephonepersonalizationcustom_variablesc d|i} |r|| d<|r|| d<|r|| d<|r|| d<|r|| d<|r|| d<|r|| d<| r| | d <| r| | d <|jd d | S)a Create a single lead. POST /leads Args: email: Lead email address (required) campaign_id: Campaign UUID to add lead to list_id: Lead list UUID to add lead to first_name: Lead first name last_name: Lead last name company_name: Lead company name website: Lead website URL phone: Lead phone number personalization: Custom personalization text custom_variables: Dict of custom variable key-value pairs. Values must be string, number, boolean, or null. Objects/arrays are NOT allowed. Returns: Created lead dict rrrZrsrtrurvrwrxryrzrcz/leadsrdrX) rrrrZrsrtrurvrwrxryrzres r create_leadzInstantlyClient.create_leadsF!(/ "-D  %DO !+D   )D  #/D %DO !DM &5D" # '7D# $}}VX}>>rleadsskip_if_in_workspaceskip_if_in_campaigncT|||d}|r||d<|r||d<|jdd|dS)a Add leads in bulk to a campaign or list. POST /leads/batch Args: leads: List of lead dicts (max 1000). Each must have at minimum 'email'. campaign_id: Campaign UUID to add leads to list_id: Lead list UUID to add leads to skip_if_in_workspace: Skip if lead exists in any workspace campaign skip_if_in_campaign: Skip if already in the target campaign (default True) Returns: Bulk operation result )r}r~rrZrsrcz /leads/batch<)r*r+rX)rr}rZrsr~rres radd_leads_bulkzInstantlyClient.add_leads_bulkLsG0$8#6  "-D  %DO}}V^tSU}VVrcjd|i}|r||d<|r||d<|r||d<|r||d<|jdd|S) a List leads with optional filters. GET /leads/search NOTE: The V2 API uses /leads/search as the list endpoint, not /leads. This endpoint requires at least a campaign_id or list_id. Args: campaign_id: Filter by campaign list_id: Filter by lead list limit: Number of results email: Filter by email address starting_after: Pagination cursor Returns: Dict with leads list rQrZrsrrrSrUz /leads/searchrWrX)rrZrsrQrrrSr)s r list_leadszInstantlyClient.list_leadspsW4#*5!1 $/F= !  'F9  #F7O '5F# $}}UOF}CCrlead_idc,|jdd|S)z Get a specific lead by ID. GET /leads/{id} Args: lead_id: Lead UUID Returns: Lead details dict rU/leads/rXrrs rget_leadzInstantlyClient.get_leads}}UggY$788rc 0|jdd||S)z Update a lead. PATCH /leads/{id} Args: lead_id: Lead UUID **kwargs: Fields to update Returns: Updated lead dict rhrrdrX)rrris r update_leadzInstantlyClient.update_leads }}Wy&9V}LLrc,|jdd|S)z Delete a lead. WARNING: This is permanent. DELETE /leads/{id} Args: lead_id: Lead UUID Returns: Deletion result rprrXrs r delete_leadzInstantlyClient.delete_leads}}X ':;;rcNd|i}|r||d<|r||d<|jdd|S)z List sent/received emails. GET /emails Args: campaign_id: Filter by campaign lead_id: Filter by lead limit: Number of results Returns: Dict with emails list rQrZrrUz/emailsrWrX)rrZrrQr)s r list_emailszInstantlyClient.list_emailss=&#*5!1 $/F= !  'F9 }}UIf}==rc.|jddd|iS)z List sending accounts. GET /accounts Args: limit: Number of results Returns: Dict with accounts list rUz /accountsrQrWrX)rrQs r list_accountszInstantlyClient.list_accountss}}UK%8H}IIrc,|jdd|S)a Get campaigns associated with a sending account email. GET /account-campaign-mappings/{email} NOTE: The V2 API only supports GET for account-campaign mappings. Assigning accounts to campaigns must be done via the Instantly dashboard. Args: email: Sending account email address Returns: List of campaign mappings for this account rUz/account-campaign-mappings/rX)rrrs rget_account_campaign_mappingsz-InstantlyClient.get_account_campaign_mappingss}}U&A%$IJJr))NNN) NNN)NN) NNNNNNNNN)NNFT)NNrNN)NNr)r)rrrrrrrrrrrPrYr^rrfrjrlrnrqr|boolrrrrrrrrrrrr#s  c *"&$('+ ETETET ET D> ET  } ET ETZ $ $(, AA A A ! A  A> A A A"+/,0 CCDJ'C$D> C  C> U3 UT U YS YT Y V# V$ V D3 D4 D*&*!%$(#'&*!%#)-598?8?c]8?# 8? SM 8? C= 8?sm8?#8?}8?"#8?#4S>28? 8?z&*!%%*$( "WDz"Wc]"W# "W # "W " "W "WL&*!%#(, $Dc]$D#$D $D } $D ! $D $DL 9 9 9 M3 MT M <3 <4 <(&*!% >c]>#> >  >> J3 J J$K3K4Krrr,cd}t|S)zn Create a client using the Genesis API key. Returns: Configured InstantlyClient instance zDMjBjODUxNGYtNjA5MC00NjY4LWFhY2UtOWZmYTE3NDhhMmQ1OnRTYkpqRU94RHJveg==)r)r)API_KEYs rget_default_clientrsUG 7 ++r__main__)levelr/z5Usage: python instantly_client.py [args...]z Commands:z* list-campaigns List all campaignsz, get-campaign Get campaign detailsz- list-accounts List sending accountsz. list-leads List leads in campaignzlist-campaigns)rQr0z get-campaignzError: campaign_id requiredz list-accountsz list-leads)rZzUnknown command: ) rr3loggingtypingrrrrr" getLoggerrr<r; Exceptionrrrsys basicConfigINFOclientlenargvprintexitcommandrYresultr>r^rrrrrrs$  ,,   8 $ -J JbKbKJ,O, zGgll+  !F 388}q EF k :; <= => >? hhqkG""&&R&0 jdjj*+ N " sxx=1  / 0 CHHQK$$SXXa[1 jdjj*+ O #%%B%/ jdjj*+ L sxx=1  / 0 CHHQK""sxx{"; jdjj*+ !'+, Ur