{"openapi":"3.1.0","info":{"title":"Mailsumo API","version":"1.0.0","description":"The Mailsumo API gives you everything the apps do, from your own code: find work email\naddresses, verify them, and read the leads and email tracking data on your account.\n\nEvery endpoint lives under `https://app.mailsumo.io/api/v1`, speaks JSON, and is included with every\npaid plan.\n\n## Authentication\n\nEvery request needs an API key, sent as a bearer token:\n\n```bash\ncurl https://app.mailsumo.io/api/v1/me \\\n  -H \"Authorization: Bearer ms_your_key_here\"\n```\n\nCreate keys on the [API keys page](https://app.mailsumo.io/api-keys) of your dashboard. A key is shown\nonce, at the moment you create it, so store it there and then.\n\nThe two single-call `GET`s, `/finder/find` and `/verify`, also take the key as an\n`api_key` query parameter, so a URL on its own is a working integration:\n\n```bash\ncurl \"https://app.mailsumo.io/api/v1/verify?email=ada@stripe.com&api_key=ms_your_key_here\"\n```\n\nReach for that when a header is awkward (a spreadsheet formula, a no-code tool's URL field)\nand for the header everywhere else: a key in a URL is a key in your access logs, your proxy\nlogs and your browser history.\n\nA key carries the full rights of your account, so keep it on your server and never ship it in\na browser or a mobile app. If a key leaks, revoke it: revocation takes effect immediately.\n\nAPI access is included with every paid plan. Without one, calls answer `402\npayment_required`.\n\n## Credits\n\nThe finder and the verifier spend the same credits as the apps do, and answer `402\ninsufficient_credits` when the allowance for the period is gone. `GET /v1/credits` tells you\nwhere you stand before a large run.\n\nFinding and verifying are `GET`s that spend, so treat them as writes: don't retry them from a\ncache, and don't put them behind one. A search that finds nothing is refunded, and an address\nwe checked recently is answered from cache for free (`charged: false`).\n\n## Rate limits\n\n120 requests per minute per account, and less where a call spends credits:\n60/min for find, 120/min for verifying one address, and\n30/min for the batch, which carries up to 500 of them. Every\nresponse carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`\n(a Unix timestamp in seconds). Read them and pace yourself rather than waiting for a 429.\n\n## Pagination\n\nCollections return at most 100 records at a time, newest first. Read\n`next_cursor` from the response and send it back as `cursor` for the following page; a\n`null` cursor means you have reached the end. Cursors are opaque: don't parse or build one.\n\n```bash\ncurl \"https://app.mailsumo.io/api/v1/leads?limit=100&cursor=Y2x4MnAw\" \\\n  -H \"Authorization: Bearer ms_your_key_here\"\n```\n\n## Errors\n\nFailures return the matching HTTP status and a JSON body. Branch on `error`, which is\nstable; `message` is written for people and may be reworded.\n\n```json\n{\n  \"error\": \"insufficient_credits\",\n  \"message\": \"No finder credits left for this billing period.\"\n}\n```\n\n| Status | Code | Meaning |\n| --- | --- | --- |\n| 400 | `invalid_request` | A parameter is missing, malformed or out of range. |\n| 401 | `unauthorized` | The key is missing, revoked, or not an API key. |\n| 402 | `payment_required` | The account has no paid plan. |\n| 402 | `insufficient_credits` | The credit allowance for the period is spent. |\n| 404 | `not_found` | No such record on this account. |\n| 429 | `rate_limited` | Too many requests. Wait for the window to reset. |\n| 500 | `internal_error` | Our fault. Safe to retry. |","contact":{"name":"Mailsumo support","email":"support@mailsumo.io"}},"servers":[{"url":"https://app.mailsumo.io/api/v1","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account","description":"Who you are and what you have left to spend."},{"name":"Finder","description":"Find a person’s work email address."},{"name":"Verifier","description":"Check whether an address can receive mail."},{"name":"Leads","description":"The addresses on your account, and how they are grouped."},{"name":"Tracking","description":"Emails you sent with the tracker, and their opens."}],"paths":{"/me":{"get":{"tags":["Account"],"summary":"Retrieve the account","description":"The account the key belongs to. Useful as a connectivity check.","operationId":"getAccount","responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"get":{"tags":["Account"],"summary":"Retrieve credit balances","description":"Finder and verifier allowances for the current billing period.","operationId":"getCredits","responses":{"200":{"description":"Both balances.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credits"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads":{"get":{"tags":["Leads"],"summary":"List leads","description":"Every address on the account, newest first, whichever tool collected it. Filter by list, by the tool that found it, or by verification status.\n\nEach lead comes with the lists it is filed in and, where we have it, the company behind its domain, so a sync does not need a second call per row.","operationId":"listLeads","parameters":[{"name":"limit","in":"query","description":"How many records to return. 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"The `next_cursor` from the previous page. Omit for the first page.","schema":{"type":"string"}},{"name":"list_id","in":"query","description":"Only leads filed in this list.","schema":{"type":"string"}},{"name":"source","in":"query","description":"Which tool collected the address.","schema":{"type":"string","enum":["extractor","finder"]}},{"name":"verification","in":"query","description":"Last known verification verdict.","schema":{"type":"string","enum":["valid","invalid","catch_all","disposable","unknown"]}}],"responses":{"200":{"description":"A page of leads.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page. `null` on the last page."}}}}}},"400":{"description":"A query parameter is out of range or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such list on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}":{"get":{"tags":["Leads"],"summary":"Retrieve a lead","description":"One lead by the id you got from `GET /v1/leads`, with the same lists and company context.","operationId":"getLead","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The lead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such lead on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Leads"],"summary":"Delete a lead","description":"Deletes the address from the account, and with it every list it was filed in. This is not reversible, and the Extractor is free to collect the address again on a later visit. To take a lead out of one list but keep it, use `DELETE /v1/lists/{id}/leads/{lead_id}`.","operationId":"deleteLead","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such lead on this account, or it is already deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists":{"get":{"tags":["Leads"],"summary":"List lead lists","description":"All lead lists, including the two system lists (Extractor and Finder) that hold whatever the tools saved. Not paginated.","operationId":"listLists","responses":{"200":{"description":"Every list on the account.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/List"}}}}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{id}":{"get":{"tags":["Leads"],"summary":"Retrieve a lead list","description":"One list. Its members come from `GET /v1/leads?list_id=...`.","operationId":"getList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/List"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such list on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{id}/leads/{lead_id}":{"delete":{"tags":["Leads"],"summary":"Remove a lead from a list","description":"Takes the lead out of this list and leaves the address on the account, still reachable through `GET /v1/leads`. To delete the address itself, use `DELETE /v1/leads/{id}`.","operationId":"removeLeadFromList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"lead_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Removed."},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such list on this account, or the lead is not in it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages":{"get":{"tags":["Tracking"],"summary":"List tracked emails","description":"Emails sent with the tracker, most recent first.","operationId":"listMessages","parameters":[{"name":"limit","in":"query","description":"How many records to return. 1 to 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"The `next_cursor` from the previous page. Omit for the first page.","schema":{"type":"string"}},{"name":"state","in":"query","description":"Stage of the send. `overflow` and `untracked` were sent without a working pixel. `overflow` is historical only: it marked sends past the old free monthly cap, which no longer exists.","schema":{"type":"string","enum":["tracked","opened","overflow","untracked"]}},{"name":"thread_id","in":"query","description":"Only the sends belonging to this Gmail thread.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of messages.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page. `null` on the last page."}}}}}},"400":{"description":"A query parameter is out of range or not recognised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/{id}/events":{"get":{"tags":["Tracking"],"summary":"Retrieve open and click events","description":"The timeline for one tracked email. Only genuine opens are listed: image proxies, link scanners and your own client are filtered out, and near-simultaneous refetches are collapsed, so the number of events matches the `opens` count on the message.","operationId":"listMessageEvents","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageEvents"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such message on this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/finder/find":{"get":{"tags":["Finder"],"summary":"Find an email address","description":"Find one person’s work email at a domain. Give a `domain` and a name, either `full_name` or `first_name` and `last_name`. A hit costs one finder credit and is saved to your leads; a miss costs nothing.\n\nThe response also carries what we know about the company at that domain, found or not, and that context is free.\n\nThere is no company-name or LinkedIn lookup: a domain is the only starting point, so resolve the company to its domain before calling.","operationId":"findEmail","security":[{"apiKeyQuery":[]},{"apiKey":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://app.mailsumo.io/api/v1/finder/find?domain=stripe.com&first_name=Ada&last_name=Lovelace&api_key=ms_your_key_here\""}],"parameters":[{"name":"domain","in":"query","required":true,"description":"The company domain, e.g. `stripe.com`. A URL or an email address also works.","schema":{"type":"string","examples":["stripe.com"]}},{"name":"full_name","in":"query","description":"The person’s full name, sent instead of `first_name` and `last_name`. Case and accents don’t matter.","schema":{"type":"string","examples":["Ada Lovelace"]}},{"name":"first_name","in":"query","required":true,"description":"The person’s first name. Not needed when you send `full_name`.","schema":{"type":"string","examples":["Ada"]}},{"name":"last_name","in":"query","required":true,"description":"The person’s last name. Not needed when you send `full_name`.","schema":{"type":"string","examples":["Lovelace"]}},{"name":"company","in":"query","description":"Saved with the lead for context. It is not used to find the address, and does not stand in for `domain`.","schema":{"type":"string"}},{"name":"position","in":"query","description":"Job title, saved with the lead for context.","schema":{"type":"string"}},{"name":"linkedin_url","in":"query","description":"The person’s LinkedIn profile, saved with the lead as where you found them.","schema":{"type":"string","format":"uri"}},{"name":"list_ids","in":"query","description":"Extra lists to file a hit under, repeated or comma-separated. It always lands in your Finder list as well.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}],"responses":{"200":{"description":"The search ran. `result` is `null` when no address could be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindResponse"}}}},"400":{"description":"The domain or the name is missing or malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/verify":{"get":{"tags":["Verifier"],"summary":"Verify one email address","description":"Check whether one address can receive mail. It costs one verifier credit, unless we checked the same address recently, in which case the cached verdict is free and `charged` is `false`.\n\nUse the `POST` on this path to check up to 500 addresses in a single call.","operationId":"verifyEmail","security":[{"apiKeyQuery":[]},{"apiKey":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://app.mailsumo.io/api/v1/verify?email=ada@stripe.com&api_key=ms_your_key_here\""}],"parameters":[{"name":"email","in":"query","required":true,"description":"The address to check.","schema":{"type":"string","format":"email","example":"ada@stripe.com"}}],"responses":{"200":{"description":"The verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyOneResponse"}}}},"400":{"description":"`email` is missing or is not an email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Verifier"],"summary":"Verify email addresses","description":"Check up to 500 addresses in one call. Each costs one verifier credit unless we checked it recently, in which case the cached verdict is free. If the allowance runs out mid-batch the remainder comes back under `skipped` instead of failing the call.","operationId":"verifyEmails","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"The verdicts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"400":{"description":"`emails` is missing, empty, too long, or not all addresses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, malformed, revoked, or not an API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no paid plan, or has run out of credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the window in `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your API key, created at https://app.mailsumo.io/api-keys."},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"The same key in the query string, accepted on the two single-call GETs so a URL can be the whole integration. Prefer the header where you can: a key in a URL is a key in your access logs and your browser history."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine-readable code. Branch on this, not on `message`.","enum":["unauthorized","payment_required","insufficient_credits","forbidden","not_found","invalid_request","rate_limited","internal_error"]},"message":{"type":"string","description":"A sentence a developer can act on."}}},"Account":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"products":{"type":"array","description":"The plans this account holds.","items":{"type":"string","enum":["extractor","finder","tracker","verifier","suite"]}},"created_at":{"type":"string","format":"date-time"}}},"Balance":{"type":"object","properties":{"allowance":{"type":"integer","description":"Credits granted for the period."},"used":{"type":"integer"},"remaining":{"type":"integer"},"period_end":{"type":"string","format":"date-time","description":"When the allowance resets. Unused credits do not roll over."}}},"Credits":{"type":"object","properties":{"finder":{"$ref":"#/components/schemas/Balance"},"verifier":{"$ref":"#/components/schemas/Balance"}}},"Lead":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"domain":{"type":"string","nullable":true},"source":{"type":"string","enum":["extractor","finder"]},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"position":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true,"description":"The employer recorded with this person, which can differ from `company.name`: one is where they said they work, the other is who owns the domain."},"linkedin_url":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true,"description":"Their photo, hosted by us rather than hotlinked, so it will not go stale or start returning a 403. Present only where we captured one."},"confidence":{"type":"integer","nullable":true,"description":"0 to 100. Only set for addresses the Finder resolved."},"verification":{"type":"string","nullable":true,"enum":["valid","invalid","catch_all","disposable","unknown"]},"verified_at":{"type":"string","format":"date-time","nullable":true},"source_url":{"type":"string","nullable":true,"description":"The page the Extractor took the address from."},"captured_at":{"type":"string","format":"date-time"},"lists":{"type":"array","description":"The lists this lead is filed in, oldest membership first.","items":{"$ref":"#/components/schemas/ListRef"}},"company":{"allOf":[{"$ref":"#/components/schemas/Company"}],"nullable":true,"description":"What we hold about the domain, or `null` where we hold nothing."}}},"ListRef":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["extractor","finder","custom"]}}},"Company":{"type":"object","description":"The company behind a domain. Coverage is uneven, so treat every field as optional: we would rather return `null` than a guess.","properties":{"domain":{"type":"string","example":"stripe.com"},"name":{"type":"string","nullable":true,"example":"Stripe"},"website":{"type":"string","nullable":true,"example":"https://stripe.com"},"logo_url":{"type":"string","nullable":true,"description":"Our copy of the logo, hosted by us, so it is safe to embed.","example":"https://assets.mailsumo.io/logos/stripe.com.png"},"employees":{"type":"integer","nullable":true,"example":8000},"founded":{"type":"integer","nullable":true,"example":2010},"description":{"type":"string","nullable":true,"example":"Financial infrastructure for the internet."},"locality":{"type":"string","nullable":true,"example":"South San Francisco"},"region":{"type":"string","nullable":true,"example":"California"},"country":{"type":"string","nullable":true,"example":"US"},"linkedin_url":{"type":"string","nullable":true,"example":"https://linkedin.com/company/stripe"},"twitter_url":{"type":"string","nullable":true,"example":"https://twitter.com/stripe"},"coverage":{"type":"object","description":"How deep we are at this domain, from our own index rather than a supplier: useful for telling a small company from one we simply do not know well yet.","properties":{"known_contacts":{"type":"integer","description":"Addresses we hold at the domain, before verification.","example":274},"pattern_confidence":{"type":"integer","description":"How sure we are of the domain’s address shape, 0 to 100. A zero means we have not learned one.","example":88}}}}},"List":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["extractor","finder","custom"],"description":"The two system lists cannot be deleted; everything else is `custom`."},"lead_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time","nullable":true}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"thread_id":{"type":"string","description":"The Gmail thread this send belongs to."},"state":{"type":"string","enum":["tracked","opened","overflow","untracked"]},"opens":{"type":"integer","description":"Genuine opens counted so far."},"first_opened_at":{"type":"string","format":"date-time","nullable":true},"last_opened_at":{"type":"string","format":"date-time","nullable":true},"sent_at":{"type":"string","format":"date-time"},"scheduled":{"type":"boolean"},"recipients":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"type":{"type":"string","enum":["to","cc","bcc"]}}}}}},"MessageEvents":{"type":"object","properties":{"message_id":{"type":"string"},"opens":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"device":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"city":{"type":"string","nullable":true}}}},"clicks":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"device":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"url":{"type":"string"}}}}}},"FindResponse":{"type":"object","properties":{"search_id":{"type":"string","description":"The search, for your own records.","example":"cmsrgzene001t156ho1fujzp0"},"result":{"type":"object","nullable":true,"properties":{"email":{"type":"string","format":"email","example":"ada@stripe.com"},"first_name":{"type":"string","nullable":true,"example":"Ada"},"last_name":{"type":"string","nullable":true,"example":"Lovelace"},"full_name":{"type":"string","nullable":true,"example":"Ada Lovelace"},"position":{"type":"string","nullable":true,"example":"Head of growth"},"confidence":{"type":"integer","description":"0 to 100.","example":96},"verification":{"type":"string","nullable":true,"enum":["valid","invalid","catch_all","disposable","unknown"],"example":"valid"},"avatar_url":{"type":"string","nullable":true,"description":"Their photo, if we already hold one for this address. A search never goes looking for one."}}},"company":{"allOf":[{"$ref":"#/components/schemas/Company"}],"nullable":true,"description":"The company at that domain, returned whether or not the person was found: a miss still tells you who you were searching."},"credits_remaining":{"type":"integer","example":431}}},"VerifyRequest":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","format":"email"},"examples":[["ada@stripe.com","grace@stripe.com"]]}}},"Verdict":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"ada@stripe.com"},"status":{"type":"string","enum":["valid","invalid","catch_all","disposable","unknown"],"example":"valid"},"confidence":{"type":"integer","description":"0 to 100.","example":96},"charged":{"type":"boolean","description":"False when a cached verdict answered, which costs nothing."}}},"VerifyOneResponse":{"allOf":[{"$ref":"#/components/schemas/Verdict"},{"type":"object","properties":{"credits_remaining":{"type":"integer","example":431}}}]},"VerifyResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Verdict"}},"credits_used":{"type":"integer","example":1},"credits_remaining":{"type":"integer","example":431},"skipped":{"type":"array","description":"Addresses left unchecked because the allowance ran out.","items":{"type":"string","format":"email","example":"grace@stripe.com"}}}}}}}