pioHdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl m Z m Z ddl mZmZddlmZddlmZmZddlmZddlZej0d Zej4ej6d eGd d ZeGddZGdde ZGddeZd#dZ GddeZ!GddeZ"GddeZ#d$d%dZ$ d& d'dZ%d(dZ&d)d*dZ'Gdd eZ(d+d!Z)e*d"k(rejVe)yy),u* Email Agent — Programmable Email Inboxes for E2E Testing ========================================================== Provides AI agents with temporary email inboxes for end-to-end testing. Supports MailSlurp, AgentMail, and Inbucket (self-hosted) backends via a unified async interface. Usage: provider = get_email_provider() inbox = await provider.create_inbox() email = await wait_for_email(provider, inbox.id, subject_contains="Verify") link = extract_verification_link(email.html) Run self-test: python testing/email_agent.py ) annotationsN)ABCabstractmethod) dataclassfield) HTMLParser)ListOptional)urlparse email_agentu&%(levelname)s %(name)s — %(message)s)levelformatcZeZdZUdZded<ded<ded<dZded<ee Zd ed <y) InboxzA temporary email inbox.strid email_addressproviderN Optional[str] created_atdefault_factorydictextra) __name__ __module__ __qualname____doc____annotations__rrrr,/mnt/e/genesis-system/testing/email_agent.pyrr,s." GM $J $-E4-r!rceZdZUdZded<ded<ded<ded<ded<d ed <d Zd ed <d Zd ed <eeZ ded<y )Emailz&An email message received in an inbox.rrinbox_idsubject from_address List[str]tor received_atNhtmltextrrr) rrrrrr+r,rrrr r!r"r$r$6sH0 GM LMD-D--E4-r!r$cveZdZdZed d dZed dZed dZed dZeddZ d ddZ y) EmailProviderz.Abstract base class for email inbox providers.Nc Kyw)z+Create a new temporary inbox and return it.Nr selfnames r" create_inboxzEmailProvider.create_inboxK  c Kyw)zAReturn all emails currently in the inbox (summary, no full body).Nr r1r%s r" get_emailszEmailProvider.get_emailsPr4r5c Kyw)z9Fetch full content (HTML + text body) for a single email.Nr r1r%email_ids r"get_email_contentzEmailProvider.get_email_contentUr4r5c Kyw)z3Return all hyperlinks found in the email HTML body.Nr r:s r" extract_linkszEmailProvider.extract_linksZr4r5c Kyw)z?Delete the inbox and all its messages. Returns True on success.Nr r7s r" delete_inboxzEmailProvider.delete_inbox_r4r5cgd}gd}tj|}tj|}tjdd}|d||||||d|||d||g}tj|}|xsd} |d | S) zIGenerate a realistic-looking human email address for the provider domain.)jamesemmaoliveravawilliamsophianoahisabellaliammiaethan charlottemasonameliajacobharpermichaelevelynjackabigail)smithjohnsonwilliamsjonesbrowndavismillerwilsonmooretaylorandersonthomasjacksonwhiteharrismartinthompsongarciamartinezrobinson c._r gmail.com@)randomchoicerandint) r1domain first_names last_namesfirstlastsuffix separatorslocal target_domains r"create_human_emailz EmailProvider.create_human_emailds   k*}}Z(B'qvh/E74&1Iqvh/E!H:dVF81LN  j)-+ -))r!Nr2rreturnrr%rrz List[Email]r%rr;rrr$r%rr;rrr(r%rrboolrsrrr) rrrrrr3r8r<r>r@r|r r!r"r.r.Hsl8          *r!r.c,eZdZdZdfd ZddZxZS)_LinkExtractorz2Minimal HTML parser that collects all href values.c0t|g|_yr})super__init__links)r1 __class__s r"rz_LinkExtractor.__init__s  " r!cl|dk(r/|D])\}}|dk(s |s|jj|+yy)Nahref)rappend)r1tagattrsattrvalues r"handle_starttagz_LinkExtractor.handle_starttags< #:$ - e6>eJJ%%e, - r!rNone)rrrlistrr)rrrrrr __classcell__rs@r"rrs<#-r!rcPt}|j||jSr})rfeedr)r+parsers r"_extract_links_from_htmlrs  F KK <<r!cfeZdZdZdZd d dZd dZd ddZddZddZ ddZ dd Z d dfd Z xZ S)MailSlurpProvideruv MailSlurp (https://mailslurp.com) — cloud temporary email service. Requires MAILSLURP_API_KEY env var. zhttps://api.mailslurp.comcd|xstjd|_|jdd|_y)NMAILSLURP_API_KEYapplication/json)z x-api-key Content-Typeosenvironapi_key_headersr1rs r"rzMailSlurpProvider.__init__s+A"**-@"A .  r!cDtj|jdSN)headerstimeouthttpx AsyncClientrr1s r"_clientzMailSlurpProvider._client  CCr!cKi}|r||d<|j4d{}|j|jd|d{}|j|j }dddd{t j ddt|d|dd|jd S77u7G#1d{7swYWxYww) Nr2z /createInboxjsonzailSlurp] Created inbox: emailAddressr mailslurp createdAtrrrr) rpostBASE_URLraise_for_statusrloggerinforgetr1r2payloadclientrespdatas r"r3zMailSlurpProvider.create_inboxs "GFO<<>  V l%C'RRD  ! ! #99;D    1$~2F1GHIDz~. xx ,    R    sWCB<C$CB> $C- C8C9AC>CCCC CCc K|j4d{}|j|jd|ddd{}|j|j }dddd{Dcgc]U}t |d||jdd|jdd|jd g|jd  Wc}S777i#1d{7swYyxYwcc}ww) Nz/getEmailsForInboxASC)inboxIdsort)paramsrr&fromr)rrr%r&r'r)r*rrrrrr$r1r%rritemsitems r"r8zMailSlurpProvider.get_emailss<<>  V==/!34#+U;$D  ! ! #IIKE   "   :!B/!XXfb188D"% HH[1           scC8CC8'CC$C' C82C3C8;AC3C8CC8C0$C' %C0, C8c .K|j4d{}|j|jd|d{}|j|j }dddd{t d||jdd|jdd|jdg|jd|jd|jd xr|jd S777#1d{7swYxYww) Nz/emails/rr&rrr)rbodybodyMD5rr%r&r'r)r*r+r,r)r1r%r;rrrs r"r<z#MailSlurpProvider.get_email_contents<<>  Vt}}oXhZ$HIID  ! ! #99;D   DzHHY+&"-xxb!-&!)$9&)9   I    sVDC:D$DC<$D$ D/C>0B D<D>DDD DDcK|j||d{}|jsgSt|jS7'wr}r<r+rr1r%r;emails r"r>zMailSlurpProvider.extract_links<,,Xx@@zzI' 33AAA(AcHK|j4d{}|j|jd|d{}dddd{tj d|dj |j dvS7o7I7;#1d{7swYKxYww)N /inboxes/z[MailSlurp] Deleted inbox : rdeleterrr status_coder1r%rrs r"r@zMailSlurpProvider.delete_inbox<<> N NV$-- ('LMMD N N 0 "T=M=Mr@r|rrs@r"rrs? +H D $ * "4 . EEr!rcfeZdZdZdZd d dZd dZd ddZddZddZ ddZ dd Z d dfd Z xZ S)AgentMailProvideruz AgentMail (https://agentmail.to) — programmable inboxes for AI agents. Requires AGENTMAIL_API_KEY env var. zhttps://api.agentmail.to/v0cj|xstjd|_d|jdd|_y)NAGENTMAIL_API_KEYzBearer r) Authorizationrrrs r"rzAgentMailProvider.__init__s2A"**-@"A &t||n5.  r!cDtj|jdSrrrs r"rzAgentMailProvider._clientrr!cKi}|r#|jjdd|d<|j4d{}|j|jd|d{}|j |j }dddd{tjddt|d|dd |jd  S77u7G#1d{7swYWxYww) N rmusernamez/inboxesrzgentMail] Created inbox: addressr% agentmailrr) lowerreplacerrrrrrrrrrs r"r3zAgentMailProvider.create_inboxs "&**,"6"6sC"@GJ <<>  V h%?gNND  ! ! #99;D    1$y/1BCDJy/ xx -    N    sX  Vt}}oYxj $RSSD  ! ! #99;D   2  V==/8*JxjID  ! ! #99;D   88D"% h $ zHL!HHY+&"-/&!&!       sWDC?D'DD$D' D2D3B DDDD D DDcK|j||d{}|jsgSt|jS7'wr}rrs r"r>zAgentMailProvider.extract_linksDrrcHK|j4d{}|j|jd|d{}dddd{tj d|dj |j dvS7o7I7;#1d{7swYKxYww)Nrz[AgentMail] Deleted inbox rrrrs r"r@zAgentMailProvider.delete_inboxJrrc*t||xsdS)Nz agentmail.torrs r"r|z$AgentMailProvider.create_human_emailPsw)&*BNCCr!r}rrr~rrrrrrrs@r"rrs? -H D $ & .4 . DDr!rcjeZdZdZd d dZd dZddZd ddZddZddZ ddZ dd Z d dfd Z xZ S)InbucketProvideru Inbucket (https://inbucket.org) — self-hosted disposable email server. Connects to Inbucket REST API. Env vars: INBUCKET_URL (default http://localhost:9000) c|xs tjjdd}|jd|_t |jj xsd|_y)N INBUCKET_URLhttp://localhost:9000/ localhost)rrrrstripbase_urlr hostname_domain)r1rraws r"rzInbucketProvider.__init___sFQ"**..9PQ 3  .77F; r!c.tjdS)Nr)rrrs r"rzInbucketProvider._clientds  ,,r!c$|d|jS)Nro)rr0s r"_make_inbox_addressz$InbucketProvider._make_inbox_addressgsq''r!cK|xs$dtjjdd}|j|}tj d|t ||dSw)Nagent_ z[Inbucket] Using inbox: inbucket)rrr)uuiduuid4hexrrrr)r1r2rzrs r"r3zInbucketProvider.create_inboxjsg8&!1!1#2!6 78007  .}o>?'  sA A"c @K|j4d{}|j|jd|d{}|jdk(rgcdddd{S|j |j xsg}dddd{Dcgc]V}t |d||jdd|jdd|jddg|jd Xc}S7777l#1d{7swY|xYwcc}ww) N/api/v1/mailbox/irr&rrmailboxdater)rrrrrrr$rs r"r8zInbucketProvider.get_emailsws<<> & &Vt}}o5EhZ$PQQD3& & & &  ! ! #IIK%2E  & &    :!B/!XXfb1HHY+, HHV,     &Q & & & & &  sDC<D$DC>D D D!D&$D DDDAD9D>DDDD D D Dc .K|j4d{}|j|jd|d|d{}|j|j }dddd{jdi}t |||jdd|jdd|jddg|jd|jd |jd  S777#1d{7swYxYww) Nr!r rr&rrr"r#r+r,r)rrrrrr$)r1r%r;rrrrs r"r<z"InbucketProvider.get_email_contents<<>  V==/!1(1XJGD  ! ! #99;D   xx#HHY+&"-B'((&!&!       sWDC:D'DC<$D' D2C>3BD<D>DDD DDcK|j||d{}|jsgSt|jS7'wr}rrs r"r>zInbucketProvider.extract_linksrrcHK|j4d{}|j|jd|d{}dddd{tj d|dj |j dvS7o7I7;#1d{7swYKxYww)Nr!znbucket] Deleted mailbox rr)rrrrrrrs r"r@zInbucketProvider.delete_inboxs<<> U UV$--8H 'STTD U U 1(2d>N>N=OPQ:-- UT U U U Urc>t||xs |jSr})rr|rrs r"r|z#InbucketProvider.create_human_emailsw)&*@DLLAAr!r})rrrrr)r2rrrr~rrrrr)rrrrrrrr3r8r<r>r@r|rrs@r"r r Xs= G -(   ( (4 . BBr!r c|xsdjj}|dk(s!|s>tjj drt j dtS|dk(s!|s>tjj drt j dtS|dk(s|sEtjj d d }t j d |d t| Std|d)u Return an EmailProvider instance. Auto-detection order (when provider_name is None): 1. MAILSLURP_API_KEY → MailSlurpProvider 2. AGENTMAIL_API_KEY → AgentMailProvider 3. INBUCKET_URL → InbucketProvider 4. fallback → InbucketProvider (localhost:9000) Args: provider_name: One of "mailslurp", "agentmail", "inbucket". If None, auto-detects from environment. rrrzEmailProvider: MailSlurprrzEmailProvider: AgentMailrr r zEmailProvider: Inbucket ()rzUnknown provider: z-. Choose from: mailslurp, agentmail, inbucket) rstriprrrrrrrr  ValueError) provider_namer2urls r"get_email_providerr/s  R & & ( . . 0D {4BJJNN;N,O ./ "" {4BJJNN;N,O ./ "" zjjnn^-DE /uA67--  ]-.6 6 r!c Ktj|z}d}tj|kr!|dz }|j|d{}|D]~}|&|j||jd{cS|j |j xsdj vsZ|j||jd{cS|tjz } tjd|dt|d| dd tjt|| d{tj|kr!td |d |d |d 77779w)aC Poll an inbox until a matching email arrives or timeout elapses. Args: provider: An EmailProvider instance. inbox_id: The inbox to poll. subject_contains: Optional substring to match against email subjects (case-insensitive). If None, returns the first email. timeout: Maximum seconds to wait before raising TimeoutError. poll_interval: Seconds between polls. Returns: The first Email matching the filter. Raises: TimeoutError: If no matching email arrives within timeout. rNrzwait_for_email attempt z: no match yet (z emails, z.0fz s remaining)z#No email matching subject_contains=z arrived in inbox z within s)time monotonicr8r<rrr&rdebuglenasynciosleepmin TimeoutError) rr%subject_containsr poll_intervaldeadlineattemptemailssummary remainings r"wait_for_emailrBsm0~~')HG .. X %1 **844 NG'%77'**MMM%%'GOO,Ar+H+H+JJ%77'**MMM  Nt~~//  %gY/F }Ii_L B mmC y9:::! .. X %$  -.>-AB$:XgYa 9 !5 NM ;sUA E3 E**E38E-94E3.E3 E/A)E37E18E3E3-E3/E31E3cJtjdtj}tjdtj}tjdtjtjz}|j |D]l}|j d|j d}}|j |s|j |sH|j}|jdsj|cS|j |D]H}|j dj}|jds4|j |sF|cS|j |D]6}|j dj}|jds4|cSy)a^ Parse email HTML and return the first verification/confirmation URL found. Looks for links whose text or href contains keywords like: verify, confirm, activate, reset, click here, get started, etc. Args: email_html: Raw HTML string of the email body. Returns: The first matching URL, or None if not found. zGverif|confirm|activat|reset|click.here|get.started|validate|unsubscribezhref=["\']([^"\']+)["\']z0]*href=["\']([^"\']+)["\'][^>]*>(.*?)r1httpN) recompile IGNORECASEDOTALLfinditergroupsearchr+ startswith) email_htmlVERIFICATION_KEYWORDS URL_PATTERNanchor_patternmatchr link_textr. href_matchs r"extract_verification_linkrU sfJJR **# K ZZ;  !N ((4++a.%++a.i ' ' -1F1M1Mi1X**,C~~f% "**:6 "((* ??6 "'<'C'CD'IK "**:6 "((* ??6 "K r!c8t}|j|S)ur Generate a realistic human-style email address on the given domain. Examples: create_human_email() → "emma.johnson45@gmail.com" create_human_email("yahoo.com") → "jsmith72@yahoo.com" This is a standalone helper; individual providers also expose this via EmailProvider.create_human_email() using their own domain. ) _NullProviderr|)rsrs r"r|r|>sH  & &v ..r!c0eZdZdZddZdZdZdZdZy) rWzBInternal stub to reuse create_human_email without a real provider.NcKtwr}NotImplementedErrorr0s r"r3z_NullProvider.create_inboxP !! cKtwr}rZr7s r"r8z_NullProvider.get_emailsSr\r]cKtwr}rZr:s r"r<z_NullProvider.get_email_contentVr\r]cKtwr}rZr:s r"r>z_NullProvider.extract_linksYr\r]cKtwr}rZr7s r"r@z_NullProvider.delete_inbox\r\r]r}) rrrrr3r8r<r>r@r r!r"rWrWMsL"""""r!rWc  Ktdd}d}tddD]y}t|}d|vr||vs Jd||jddjddjd dj s Jd |td |{td |d z }tdd}t |}t |dk(sJdt |d|vsJtd|td |d z }tdd}t|}|dk(s Jd|td|td |d z }tdd}t|} | dk(s Jd| td| td |d z }tdtd} | Jd| td td |d z }td!d"D]"} tjj| d$t} t| tsJd#t| td$t| jd%td |d z }td&td'} t| tsJtd(t| jtd |d z }td)td*+}|j}d,|vs Jd-|td.|t j#t }d/|_i|_|j}d0|vs Jd1|td2|td |d z }td3Gd4d5t}|} t)|d6d7d89d{td:|d z }td<t-d=d>d?d@dAgdBdCDGfdEdFt}|}t)|d>dGdHId{}|j.d=k(sJdG|j0j3vsJtdJ|j0td |d z }tdKtjj5dLdM} t7j8dN4d{}|j5|dOd{}dddd{j:dPk(r0tdQ|dR|j=td |d z }ntdS|j:dTtdWtdX|dY|dZ|r td[n td\tdWd]y7#t*$r)}td;|td |d z }Yd}~d}~wwxYw77 77#1d{7swYxYw#t>$r}tdU|dVYd}~d}~wwxYww)^Nz === Email Agent Self-Test === rzTest 1: create_human_email())rnz yahoo.comrroz Bad address: rlrrmzNon-alphanum local part: z z PASSED r1z"Test 2: _extract_links_from_html()z Verify your email Home Contact zExpected 3 links, got z'https://example.com/verify?token=abc123z Links found: z#Test 3: extract_verification_link()z

Click below to verify your account:

Verify your email Back to site z3https://app.example.com/verify?token=xyz789&user=42z Wrong link: z Extracted: zATest 4: extract_verification_link() fallback (no keyword in text)zq Click here z(https://accounts.example.com/confirm/abczWrong: z=Test 5: extract_verification_link() returns None for no linksz'No links herezExpected None, got: z Result: Nonez+Test 6: get_email_provider() auto-detection)rrzExpected InbucketProvider, got z Auto-detected: u (no API keys set → Inbucket)z&Test 7: get_email_provider('inbucket')rz Got: z,Test 8: Provider.create_human_email() domainzhttp://mail.internal:9000r*z mail.internalzExpected mail.internal domain: z Inbucket address: dummyrzExpected mailslurp.com: z MailSlurp address: z=Test 9: wait_for_email() raises TimeoutError when inbox emptyceZdZdZdZdZy)&_run_self_test.._EmptyProviderc d|_d|_yNr rrrrs r"rz/_run_self_test.._EmptyProvider.__init__3DM&DLr!cKgSwr}r r7s r"r8z1_run_self_test.._EmptyProvider.get_emailss IscKtwr}rZr:s r"r<z8_run_self_test.._EmptyProvider.get_email_contents % %r]Nrrrrr8r<r r!r"_EmptyProviderrfs '  &r!rn test_inboxrDg?)rr<u, FAILED — should have raised TimeoutErrorz Got TimeoutError as expected: z0Test 10: wait_for_email() returns matching emaile001box1zPlease verify your accountznoreply@app.comzagent@test.comz2026-02-27T00:00:00Zz1Verify)rr%r&r'r)r*r+c(eZdZdZfdZfdZy)*_run_self_test.._PopulatedProviderc d|_d|_yrhrirs r"rz3_run_self_test.._PopulatedProvider.__init__rjr!cKgSwr}r )r1r% sample_emails r"r8z5_run_self_test.._PopulatedProvider.get_emailss > !scKSwr}r )r1r%r;rvs r"r<z<_run_self_test.._PopulatedProvider.get_email_contents  sNrm)rvsr"_PopulatedProviderrss ' " r!rxverify)r;rz Received: z?Test 11: InbucketProvider connectivity (skipped if not running)r r rz/api/v1/statusrz Inbucket LIVE at rz Inbucket responded u — skippedz Inbucket not reachable (u) — skipped (not a failure) z(========================================z Results: z passed, z failedzSOME TESTS FAILEDzALL TESTS PASSED ) printr|splitrisalnumrr6rUrrpopr/rr typerr__new__rrrBr:r$rr&rrrrrr Exception)passedfailedrsaddr sample_htmlrverification_htmllink plain_htmllink2resultvarrp inbucket_p mailslurp_pms_addrrnemptyerxr result_email inbucket_urlrrexcrvs @r"_run_self_testrds\ -. F F ()=!&)d{v~Etf/EE-zz#q!))#r2::3CKKM /'v . /M 4&k   , aKF ./K %[ 1E u:?A4SZLAA? 4 == = OE7 #$ , aKF /0 %%6 7D H H tf H M$ ! , aKF MNJ &j 1E > >Q'%@QQ > M% !" , aKF IJ &'P QF >:1&::>  , aKF 78:" sD!""#H h 0 1; )$x.)9:; 1 d8n5566U VW , aKF 23:&A a) ** * GDG$$% &' , aKF 89!+FGJ  ( ( *D d "L&EdV$LL "  '(#++,=>K!KK,,.G g %K)A''KK % !' +, , aKF IJ &) &  EUL!3OOO <=!  <= ,&  * @L  -    C' VhL ??f $$ $ |++113 33 3 L--. /0 , aKF KL::>>.2IJL Q$$Q/ E E6|nN$CDDD E E   s " ' ~R }E F ,  aKF )$*:*:);<H I  XJ IfXYvhg 67  !"  ! XJb/A P  045 l! < ED E E E E Q *3%/NOPPQsM>WU%U"U%)AW1V2BW9V9VV9V$/V 0V$4 V9?V"AV9AW"U%% V.V WVWV9 V$"V9$V6*V- +V62V99 WWWWW__main__)r+rrr(r})r-rrr.)N<g@) rr.r%rr;rrintr<floatrr$)rNrrr)rn)rsrrrr),r __future__rr7loggingrrprFr3rabcrr dataclassesrr html.parserrtypingr r urllib.parser r getLoggerr basicConfigINFOrr$r.rrrrr r/rBrUr|rWrrrunr r!r"rso"# #("!!   = )',,/WX .. .  . .  ."1*C1*p -Z -WE WE|[D [DDTB}TBv T'+ 000$0 0  0  0f.b /"M".{| zGKK !r!