# Email

The Email module collects a user's email address and can confirm email ownership by sending a one-time password (OTP) to that address.

For an overview of this module and how it works, see [Email Input](https://developer.incode.com/docs/email-input).

How you use this module depends on your [integration pattern](https://developer.incode.com/docs/android-common-implementation-patterns#integration-patterns). In Patterns 1 and 2, you add the module to a `FlowConfig` in code as shown on this page. In Pattern 3, you define your modules and configuration in Dashboard as a Flow or Workflow and reference it by ID with `startFlow()` or `startWorkflow()` as shown on [Run Flows Configured in Dashboard](https://developer.incode.com/docs/android-run-flows-configured-online).

## Add Email

1. Add the module with `addEmail()` (default config) or `addEmail(email)` (custom config):

```kotlin
flowConfigBuilder.addEmail()
// or with a configured instance:
flowConfigBuilder.addEmail(email)
```
```java
flowConfigBuilder.addEmail();
// or with a configured instance:
flowConfigBuilder.addEmail(email);
```

2. If your flow also uses the [Conference](https://developer.incode.com/docs/android-conference-assisted-video) or [Approval](https://developer.incode.com/docs/android-approval) modules, add them after Email.

Email ships both a v1 (legacy View) and a v2 (Jetpack Compose) capture screen; the active one depends on your Incode configuration. Contact your Incode representative to enable v2.

### Example

The example below builds an `Email` module with OTP verification enabled, adds it to the flow, and listens for the result through `onAddEmailCompleted()`.

```kotlin
val email = Email.Builder()
    .setOtpVerificationEnabled(true)
    .build()

val flowConfig = FlowConfig.Builder()
    .addEmail(email)
    .build()

val onboardingListener = object : OnboardingListener() {
    override fun onAddEmailCompleted(emailAddressResult: EmailAddressResult) {
        // Email captured. Process the result.
    }
}

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener)
```
```java
Email email = new Email.Builder()
    .setOtpVerificationEnabled(true)
    .build();

FlowConfig flowConfig = new FlowConfig.Builder()
    .addEmail(email)
    .build();

IncodeWelcome.OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onAddEmailCompleted(@NonNull EmailAddressResult emailAddressResult) {
        // Email captured. Process the result.
    }
};

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener);
```

## Configuration Options

Configure the module with `Email.Builder`. The table below lists the available option.

| Setting                              | Description                                                                                                                                                                                                                              |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setOtpVerificationEnabled(Boolean)` | If `true`, shows OTP verification after the user enters an email address. Defaults to `false`. In [Capture-Only mode](https://developer.incode.com/docs/android-capture-only-sdk), OTP is not activated even when enabled. |

For the complete option set, see `Email.Builder` in [API Reference](https://developer.incode.com/docs/android-api-reference).

## Result

Email delivers an `EmailAddressResult` to the `onAddEmailCompleted(EmailAddressResult)` callback on the `OnboardingListener`. Key fields include:

- `email`: The email address the user entered; `null` when unavailable.
- Fields inherited from `BaseResult`:
  - `resultCode`: The `ResultCode` for this result.
  - `error`: When `resultCode` is `ERROR`, the `Throwable` that caused it; otherwise, `null`.
  - `deviceStats`: The `DeviceStats` snapshot of the device state when the result was produced.
  - `motionStatus`: Device motion assessment during capture. One of the following:
    - `UNCLEAR`: Motion could not be determined; the default.
    - `PASS`: Device motion was within acceptable limits.
    - `FAIL`: Excessive device motion was detected.

If the step fails, the error surfaces via `OnboardingListener.onError(Throwable)`. Email does not define a module-specific exception subtype.

For all fields, see `EmailAddressResult` in [API Reference](https://developer.incode.com/docs/android-api-reference).