Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

17.4 KB
Raw Blame
use axum::{
    Json, Router,
    extract::{self, State},
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::post,
};
use model::response::ErrorResponse;
use thiserror::Error;
use tower::ServiceBuilder;
use tracing::Level;
use utoipa::ToSchema;

use crate::api::{context::ApiContext, middleware, utils::default_redirect_url};

const DESKTOP_EMAIL_SUBJECT: &str = "Continue onboarding on desktop";

#[derive(Debug, Error)]
pub enum SendMobileWelcomeEmailError {
    #[error("Invalid email address")]
    InvalidEmail,

    #[error("Email is blocked")]
    EmailBlocked,

    #[error("Please use your work email or Gmail")]
    PersonalEmail,

    #[error("Internal error")]
    InternalError(#[from] anyhow::Error),
}

impl IntoResponse for SendMobileWelcomeEmailError {
    fn into_response(self) -> Response {
        let status_code = match &self {
            SendMobileWelcomeEmailError::InvalidEmail
            | SendMobileWelcomeEmailError::EmailBlocked
            | SendMobileWelcomeEmailError::PersonalEmail => StatusCode::BAD_REQUEST,
            SendMobileWelcomeEmailError::InternalError(error) => {
                tracing::error!(error = ?error, "mobile welcome email failed");
                StatusCode::INTERNAL_SERVER_ERROR
            }
        };

        (
            status_code,
            Json(ErrorResponse {
                message: self.to_string().into(),
            }),
        )
            .into_response()
    }
}

/// Ad parameters from the page that captured the email.
///
/// Only these keys are copied onto the desktop link. Anything else in the
/// JSON is ignored, and values that are empty, too long, or not safe to put
/// in a URL are dropped.
#[derive(Debug, Default, Clone, serde::Deserialize, serde::Serialize)]
pub struct MobileWelcomeAttribution {
    #[serde(default)]
    pub utm_source: Option<String>,
    #[serde(default)]
    pub utm_medium: Option<String>,
    #[serde(default)]
    pub utm_campaign: Option<String>,
    #[serde(default)]
    pub utm_term: Option<String>,
    #[serde(default)]
    pub utm_content: Option<String>,
    #[serde(default)]
    pub fbclid: Option<String>,
    #[serde(default)]
    pub gclid: Option<String>,
    #[serde(default)]
    pub twclid: Option<String>,
    #[serde(default)]
    pub rdt_cid: Option<String>,
}

#[derive(Debug, serde::Deserialize, serde::Serialize, ToSchema)]
pub struct SendMobileWelcomeEmailRequest {
    /// The email address to send the welcome email to
    pub email: String,
    /// Ad parameters from the capture page. Omitted when the visit had none.
    ///
    /// Left out of the generated schema: the web and marketing clients send
    /// the object directly, and the public SDK skips this endpoint.
    #[serde(default)]
    #[schema(ignore)]
    pub attribution: MobileWelcomeAttribution,
}

#[derive(Debug, serde::Serialize, ToSchema)]
pub struct SendMobileWelcomeEmailResponse {
    /// Whether the lead was enrolled (false if they were already enrolled previously)
    pub sent: bool,
}

pub fn router(state: ApiContext) -> Router<ApiContext> {
    Router::new().route(
        "/mobile-welcome-email",
        post(handler).layer(
            ServiceBuilder::new().layer(axum::middleware::from_fn_with_state(
                state,
                middleware::rate_limit::mobile_welcome_email::handler,
            )),
        ),
    )
}

/// Emails a mobile lead a link to continue onboarding on desktop and enrolls
/// them in the Loops welcome sequence. No-ops if the address was already
/// captured, and rejects blocked addresses.
#[utoipa::path(
    post,
    path = "/mobile-welcome-email",
    operation_id = "send_mobile_welcome_email",
    responses(
        (status = 200, body = SendMobileWelcomeEmailResponse),
        (status = 400, body = ErrorResponse),
        (status = 429, body = ErrorResponse),
        (status = 500, body = ErrorResponse),
    )
)]
#[tracing::instrument(skip(ctx), fields(email=%req.email), err(level = Level::INFO))]
pub async fn handler(
    State(ctx): State<ApiContext>,
    extract::Json(req): extract::Json<SendMobileWelcomeEmailRequest>,
) -> Result<Json<SendMobileWelcomeEmailResponse>, SendMobileWelcomeEmailError> {
    if !email_validator::is_valid_email(&req.email) {
        return Err(SendMobileWelcomeEmailError::InvalidEmail);
    }

    if is_personal_email(&req.email) {
        return Err(SendMobileWelcomeEmailError::PersonalEmail);
    }

    let lowercase_email = loops_client::normalize_email(&req.email);

    // Check if the email is blocked
    let blocked_emails =
        macro_db_client::blocked_email::get_blocked_emails(&ctx.db, &[&lowercase_email]).await?;

    if !blocked_emails.is_empty() {
        return Err(SendMobileWelcomeEmailError::EmailBlocked);
    }

    // Atomically claim the slot — returns false if the email was already sent
    let inserted =
        mobile_welcome_email_db_client::mobile_welcome_email::insert_mobile_welcome_email(
            &ctx.db,
            &lowercase_email,
        )
        .await?;

    if !inserted {
        return Ok(Json(SendMobileWelcomeEmailResponse { sent: false }));
    }

    // The "continue on desktop" link the phone confirmation screen promises.
    // The capture page's ad parameters ride along so the laptop session,
    // which is a different browser, still has them for PostHog.
    let url = desktop_signup_url(&default_redirect_url(), &req.attribution);
    if let Err(e) = ctx
        .ses_client
        .send_email(
            "[email protected]",
            req.email.trim(),
            DESKTOP_EMAIL_SUBJECT,
            &desktop_email_html(&url),
        )
        .await
    {
        tracing::error!(error=?e, "failed to send mobile desktop-link email");
        // Release the claim so a retry sends the email instead of no-oping.
        if let Err(release_err) =
            mobile_welcome_email_db_client::mobile_welcome_email::delete_mobile_welcome_email(
                &ctx.db,
                &lowercase_email,
            )
            .await
        {
            tracing::error!(error=?release_err, "failed to release mobile welcome email claim");
        }
        return Err(SendMobileWelcomeEmailError::InternalError(e));
    }

    // Enrolls the lead in the Loops welcome drip. Awaited rather than
    // fire-and-forget: `sent: true` tells the caller mail is on the way, so it
    // must not report success on a Loops failure. The key is namespaced by
    // event so it can't collide with the `user_registered` event sent when the
    // lead converts.
    ctx.loops_client
        .send_event(
            &lowercase_email,
            "mobile_lead_captured",
            // `hasAccount` is set explicitly rather than left unset: the
            // workflow's audience filter tests `isFalse`, which an absent
            // property would not satisfy.
            &serde_json::json!({
                "signupStage": "lead",
                "hasAccount": false,
                "source": "mobile-lead-capture",
            }),
            Some(&format!("mobile-lead-{lowercase_email}")),
        )
        .await
        .map_err(|e| SendMobileWelcomeEmailError::InternalError(e.into()))?;

    Ok(Json(SendMobileWelcomeEmailResponse { sent: true }))
}

/// Gmail domains accepted despite being generic: Macro connects Gmail inboxes,
/// so a Gmail lead can finish signing up on desktop.
const ALLOWED_PERSONAL_DOMAINS: &[&str] = &["gmail.com", "googlemail.com"];

fn is_personal_email(email: &str) -> bool {
    email.trim().rsplit_once('@').is_some_and(|(_, domain)| {
        generic_email_domains::is_generic_email_domain(domain)
            && !ALLOWED_PERSONAL_DOMAINS
                .iter()
                .any(|allowed| domain.eq_ignore_ascii_case(allowed))
    })
}

/// Marks a signup that started from the mobile email capture, as opposed to
/// someone who opened the ad on a computer and signed up directly.
const SIGNUP_FLOW_PARAM: &str = "signup_flow";
const SIGNUP_FLOW_MOBILE_EMAIL: &str = "mobile_email";

/// Campaign names and click ids are short. Longer values are not attribution.
const MAX_ATTRIBUTION_VALUE_CHARS: usize = 512;

/// Desktop signup page. The local frontend origin has no `/app` prefix.
///
/// Copies the allowlisted ad parameters and always sets
/// `signup_flow=mobile_email`. The flow parameter is not taken from the
/// request, so a caller cannot relabel the link.
fn desktop_signup_url(base: &url::Url, attribution: &MobileWelcomeAttribution) -> String {
    let mut url = base.clone();
    let path = url.path().trim_end_matches('/').to_string();
    url.set_path(&format!("{path}/signup"));
    url.set_query(None);
    {
        let mut pairs = url.query_pairs_mut();
        for (key, value) in [
            ("utm_source", attribution.utm_source.as_deref()),
            ("utm_medium", attribution.utm_medium.as_deref()),
            ("utm_campaign", attribution.utm_campaign.as_deref()),
            ("utm_term", attribution.utm_term.as_deref()),
            ("utm_content", attribution.utm_content.as_deref()),
            ("fbclid", attribution.fbclid.as_deref()),
            ("gclid", attribution.gclid.as_deref()),
            ("twclid", attribution.twclid.as_deref()),
            ("rdt_cid", attribution.rdt_cid.as_deref()),
        ] {
            let Some(value) = value.and_then(accepted_attribution_value) else {
                continue;
            };
            pairs.append_pair(key, value);
        }
        pairs.append_pair(SIGNUP_FLOW_PARAM, SIGNUP_FLOW_MOBILE_EMAIL);
    }
    url.to_string()
}

/// Keeps values that can sit in a query string and an HTML attribute.
fn accepted_attribution_value(value: &str) -> Option<&str> {
    let value = value.trim();
    if value.is_empty() || value.chars().count() > MAX_ATTRIBUTION_VALUE_CHARS {
        return None;
    }
    if value
        .chars()
        .any(|c| c.is_control() || matches!(c, '<' | '>' | '"' | '\'' | '`' | '\\'))
    {
        return None;
    }
    Some(value)
}

fn escape_html_attr(value: &str) -> String {
    value
        .replace('&', "&amp;")
        .replace('"', "&quot;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}

fn desktop_email_html(url: &str) -> String {
    let url = escape_html_attr(url);
    format!(
        r##"<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="x-apple-disable-message-reformatting" />
    <meta name="color-scheme" content="light" />
    <meta name="supported-color-schemes" content="light" />
    <title>{DESKTOP_EMAIL_SUBJECT}</title>
  </head>
  <body style="margin:0;padding:0;width:100%;background-color:#f5f5f4;">
    <div style="display:none;max-height:0;overflow:hidden;opacity:0;mso-hide:all;">
      Open this link on desktop to finish signing up for Macro.
    </div>
    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" bgcolor="#f5f5f4" style="font-family:Arial,Helvetica,sans-serif;color:#222222;">
      <tr>
        <td align="center" style="padding:48px 20px;">
          <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:560px;">
            <tr>
              <td bgcolor="#ffffff" style="padding:36px 40px 40px;border:1px solid #e7e7e5;border-radius:12px;">
                <a href="https://macro.com" style="text-decoration:none;">
                  <img src="https://macro.com/app/macro-email-icon.png" width="48" height="48" alt="Macro" style="display:block;border:0;" />
                </a>
                <h1 style="margin:36px 0 16px;font-size:28px;line-height:36px;font-weight:600;letter-spacing:-0.5px;color:#222222;">{DESKTOP_EMAIL_SUBJECT}</h1>
                <p style="margin:0 0 20px;font-size:16px;line-height:26px;color:#525252;">Macro is a better experience on desktop. Open this link to finish signing up — it only takes a minute.</p>
                <table role="presentation" cellpadding="0" cellspacing="0" style="margin:28px 0 8px;">
                  <tr>
                    <td bgcolor="#222222" style="border-radius:6px;text-align:center;">
                      <a href="{url}" style="display:inline-block;padding:14px 24px;border:1px solid #222222;border-radius:6px;color:#ffffff;background-color:#222222;font-size:15px;line-height:20px;font-weight:600;text-decoration:none;">Continue on desktop</a>
                    </td>
                  </tr>
                </table>
                <p style="margin:28px 0 0;font-size:14px;line-height:22px;color:#737373;">If you didn't request this, you can safely ignore this email.</p>
              </td>
            </tr>
            <tr>
              <td style="padding:24px 16px 0;text-align:center;font-size:12px;line-height:20px;color:#737373;">
                Need a hand? <a href="mailto:[email protected]" style="color:#525252;text-decoration:underline;">Contact support</a>
              </td>
            </tr>
          </table>
        </td>
      </tr>
    </table>
  </body>
</html>"##
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    fn query(url: &str) -> Vec<(String, String)> {
        url::Url::parse(url)
            .unwrap()
            .query_pairs()
            .map(|(key, value)| (key.into_owned(), value.into_owned()))
            .collect()
    }

    #[test]
    fn desktop_link_points_at_signup() {
        let prod = url::Url::parse("https://macro.com/app").unwrap();
        assert_eq!(
            desktop_signup_url(&prod, &MobileWelcomeAttribution::default()),
            "https://macro.com/app/signup?signup_flow=mobile_email"
        );
        let local = url::Url::parse("http://localhost:3000").unwrap();
        assert_eq!(
            desktop_signup_url(&local, &MobileWelcomeAttribution::default()),
            "http://localhost:3000/signup?signup_flow=mobile_email"
        );
    }

    #[test]
    fn desktop_link_keeps_ad_parameters_from_the_capture_page() {
        let prod = url::Url::parse("https://macro.com/app").unwrap();
        let url = desktop_signup_url(
            &prod,
            &MobileWelcomeAttribution {
                utm_source: Some("  facebook  ".into()),
                utm_medium: Some("paid".into()),
                utm_campaign: Some("spring & summer".into()),
                utm_term: Some("lookalike".into()),
                utm_content: Some("video a".into()),
                fbclid: Some("IwAR123".into()),
                gclid: None,
                twclid: None,
                rdt_cid: None,
            },
        );
        assert_eq!(
            query(&url),
            vec![
                ("utm_source".into(), "facebook".into()),
                ("utm_medium".into(), "paid".into()),
                ("utm_campaign".into(), "spring & summer".into()),
                ("utm_term".into(), "lookalike".into()),
                ("utm_content".into(), "video a".into()),
                ("fbclid".into(), "IwAR123".into()),
                ("signup_flow".into(), "mobile_email".into()),
            ]
        );
    }

    #[test]
    fn desktop_link_drops_values_that_cannot_be_a_query_parameter() {
        let prod = url::Url::parse("https://macro.com/app").unwrap();
        let url = desktop_signup_url(
            &prod,
            &MobileWelcomeAttribution {
                utm_source: Some("facebook".into()),
                utm_campaign: Some("<script>alert(1)</script>".into()),
                utm_content: Some(" ".into()),
                utm_term: Some("x".repeat(513)),
                ..MobileWelcomeAttribution::default()
            },
        );
        assert_eq!(
            query(&url),
            vec![
                ("utm_source".into(), "facebook".into()),
                ("signup_flow".into(), "mobile_email".into()),
            ]
        );
        let html = desktop_email_html(&url);
        assert!(html.contains("&amp;"));
        assert!(!html.contains("<script"));
        assert!(html.contains(DESKTOP_EMAIL_SUBJECT));
    }

    #[test]
    fn attribution_json_uses_the_query_parameter_names() {
        let parsed: SendMobileWelcomeEmailRequest = serde_json::from_str(
            r#"{"email":"lead","attribution":{"utm_source":"facebook","fbclid":"x","signup_flow":"nope"}}"#,
        )
        .unwrap();
        assert_eq!(parsed.attribution.utm_source.as_deref(), Some("facebook"));
        assert_eq!(parsed.attribution.fbclid.as_deref(), Some("x"));
        let url = desktop_signup_url(
            &url::Url::parse("https://macro.com/app").unwrap(),
            &parsed.attribution,
        );
        let has_mobile_email_flow = query(&url)
            .iter()
            .any(|(key, value)| key == "signup_flow" && value == "mobile_email");
        assert!(has_mobile_email_flow);

        let bare: SendMobileWelcomeEmailRequest =
            serde_json::from_str(r#"{"email":"lead"}"#).unwrap();
        assert!(bare.attribution.utm_source.is_none());
    }

    #[test]
    fn desktop_email_links_to_signup() {
        let html = desktop_email_html("https://macro.com/app/signup");
        assert!(html.contains(r#"href="https://macro.com/app/signup""#));
        assert!(html.contains(DESKTOP_EMAIL_SUBJECT));
    }

    #[test]
    fn personal_email_providers_other_than_gmail_are_rejected() {
        assert!(!is_personal_email("[email protected]"));
        assert!(!is_personal_email(" [email protected] "));
        assert!(!is_personal_email("[email protected]"));
        assert!(is_personal_email("[email protected]"));
        assert!(is_personal_email(" [email protected] "));
        assert!(!is_personal_email("[email protected]"));
        assert!(!is_personal_email("[email protected]"));
    }
}