Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

5.3 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.mailtrap._config import MailtrapSourceConfig
from products.warehouse_sources.sources.mailtrap.mailtrap import (
    MailtrapResumeConfig,
    mailtrap_source,
    validate_credentials,
)
from products.warehouse_sources.sources.mailtrap.settings import ENDPOINTS, INCREMENTAL_FIELDS, MAILTRAP_ENDPOINTS
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    build_endpoint_schemas,
    detect,
)


@SourceRegistry.register
class MailtrapSource(ResumableSource[MailtrapSourceConfig, MailtrapResumeConfig]):
    codebase_detection = detect(
        env=("^MAILTRAP_",),
        npm=("mailtrap",),
        pypi=("mailtrap",),
        composer=("railsware/mailtrap-php",),
        maven=("io.mailtrap:mailtrap-java",),
        rubygems=("mailtrap",),
    )

    api_docs_url = "https://docs.mailtrap.io/developers"

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.MAILTRAP

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.MAILTRAP,
            category=DataWarehouseSourceCategory.MARKETING___EMAIL,
            label="Mailtrap",
            releaseStatus=ReleaseStatus.GA,
            caption="""Enter your Mailtrap API token to pull your email sending data into the PostHog Data warehouse.

You can create an API token under **Settings → API Tokens** in [Mailtrap](https://mailtrap.io). The token needs access to the accounts and sending domains you want to sync; email logs are restricted to the domains the token can access.
""",
            iconPath="/static/services/mailtrap.png",
            docsUrl="https://posthog.com/docs/cdp/sources/mailtrap",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_token",
                        label="API token",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
        )

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.mailtrap.canonical_descriptions import (
            CANONICAL_DESCRIPTIONS,  # noqa: PLC0415
        )

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error: Unauthorized for url: https://mailtrap.io": "Your Mailtrap API token is invalid or has been revoked. Create a new token under Settings → API Tokens, then reconnect.",
            "403 Client Error: Forbidden for url: https://mailtrap.io": "Your Mailtrap API token does not have access to this data. Check the token's account and domain permissions, then reconnect.",
        }

    def get_schemas(
        self,
        config: MailtrapSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        # Only email_logs (filters[sent_after]) and suppressions (start_time) expose a server-side
        # timestamp bound; the other endpoints are full refresh only.
        return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)

    def validate_credentials(
        self,
        config: MailtrapSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        # One cheap probe (/api/accounts) confirms the token is genuine; every token can list the
        # accounts it has access to.
        return validate_credentials(config.api_token)

    def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[MailtrapResumeConfig]:
        return ResumableSourceManager[MailtrapResumeConfig](inputs, MailtrapResumeConfig)

    def source_for_pipeline(
        self,
        config: MailtrapSourceConfig,
        resumable_source_manager: ResumableSourceManager[MailtrapResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        if inputs.schema_name not in MAILTRAP_ENDPOINTS:
            raise ValueError(f"Unknown Mailtrap schema '{inputs.schema_name}'")

        return mailtrap_source(
            api_token=config.api_token,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            resumable_source_manager=resumable_source_manager,
            should_use_incremental_field=inputs.should_use_incremental_field,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
        )