
<SdkPage group="lead" />

<Method id="subscribe" signature="subbly.lead.subscribe(payload)">

Saves an email address as a lead. Use it to catch an address early, such as on
a newsletter box or the first step of a survey, before the customer reaches
checkout.

<Params>
  <Param name="payload" required type="LeadSubscribePayload">
    The lead to save.
    <Properties label="payload">
      <Param name="email" required type="string">
        Email address of the lead.
      </Param>

      <Param name="firstName" optional type="string | null">
        Given name of the lead.
      </Param>

      <Param name="lastName" optional type="string | null">
        Family name of the lead.
      </Param>

      <Param name="metadata" optional type="Record<string, any>">
        Your own data to keep with the lead, such as the page it came from.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<LeadSubscribeResponse>">
The lead record Subbly saved.
<Properties>
  <Param name="id" type="number">
    ID of the lead.
  </Param>

  <Param name="email" type="string">
    The email address saved.
  </Param>

  <Param name="firstName" type="string | null">
    Given name of the lead.
  </Param>

  <Param name="lastName" type="string | null">
    Family name of the lead.
  </Param>

  <Param name="ipAddress" type="string">
    IP address Subbly saw on the request.
  </Param>

  <Param name="userAgent" type="string">
    Browser Subbly saw on the request.
  </Param>
</Properties>
</Returns>

<Example>

```js title="Capture a lead"
const lead = await subbly.lead.subscribe({
  email: 'me@example.com',
  firstName: 'Ada',
  metadata: { source: 'footer-form' }
})
```

</Example>

</Method>
