Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
pub(crate) mod attachments;
pub(crate) mod auth;
pub(crate) mod contacts;
mod error;
pub(crate) mod filters;
pub(crate) mod history;
pub(crate) mod labels;
pub(crate) mod messages;
pub(crate) mod profile;
pub(crate) mod send_as;
pub(crate) mod threads;
pub(crate) mod watch;
#[cfg(test)]
mod test;
use regex::Regex;
use std::sync::LazyLock;
use std::time::Duration;
const MAX_ERROR_BODY_LEN: usize = 1024;
// A stalled request fails instead of holding its worker, and its mailbox's
// request-gate permit, indefinitely. Callers size permit leases above this.
const REQUEST_TIMEOUT: Duration = Duration::from_secs(60);
const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
static EMAIL_REGEX: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}").unwrap());
/// Sanitize a Gmail API error body: redact email addresses, cap length.
pub(crate) fn sanitize_error_body(body: &str) -> String {
let redacted = EMAIL_REGEX.replace_all(body, "[REDACTED_EMAIL]");
let trimmed = redacted.trim();
if trimmed.len() <= MAX_ERROR_BODY_LEN {
return trimmed.to_string();
}
let truncate_at = trimmed
.char_indices()
.map(|(index, _)| index)
.take_while(|index| *index <= MAX_ERROR_BODY_LEN)
.last()
.unwrap_or(0);
format!("{}… (truncated)", &trimmed[..truncate_at])
}
use crate::auth::{fetch_google_public_keys, verify_google_jwt};
use crate::contacts::get_self_connection;
use crate::messages::{get_message, get_message_label_ids, list_messages};
use crate::threads::get_thread;
pub use error::GmailApiHttpError;
use models_email::gmail::contacts::{ConnectionsResponse, OtherContactsResponse, PersonResource};
pub use models_email::gmail::filters::Filter;
use models_email::gmail::inbox_sync::{
GoogleJwtClaims, GooglePublicKeys, JwtVerificationError, KeyMap,
};
use models_email::gmail::labels::GmailLabel;
use models_email::gmail::{
GmailUserProfile, HistoryListResponse, ListThreadsResponse, MessageResource, ThreadResource,
};
#[derive(Clone, Debug)]
pub struct GmailClient {
/// The inner client used to make requests
inner: reqwest::Client,
/// Sending crosses a durable submission boundary and must never be retried
/// or redirected automatically by the transport.
send_client: reqwest::Client,
/// The base url for Gmail API
base_url: String,
/// The url for fetching google certs
certs_url: String,
/// The url for fetching contact information via People API
contacts_url: String,
/// The expected audience for the jwt passed by Google
audience: String,
/// The GCP topic name we listen on for inbox updates
subscription_topic: Option<String>,
}
impl GmailClient {
/// Client for API calls that do not register push subscriptions.
pub fn without_watch() -> Self {
Self::new_with_urls(
None,
"https://www.googleapis.com/gmail/v1".to_string(),
"https://people.googleapis.com/v1".to_string(),
"https://www.googleapis.com/oauth2/v3/certs".to_string(),
"macro-gmail-webhook".to_string(),
)
}
pub fn new(subscription_topic: String) -> Self {
Self::new_with_urls(
subscription_topic,
"https://www.googleapis.com/gmail/v1".to_string(),
"https://people.googleapis.com/v1".to_string(),
"https://www.googleapis.com/oauth2/v3/certs".to_string(),
"macro-gmail-webhook".to_string(),
)
}
/// Creates a client with injectable Gmail, People, and JWKS URLs.
///
/// This constructor supports deterministic tests and Gmail-compatible
/// endpoints. HTTP transport details and endpoint values remain private to
/// this crate.
pub fn new_with_urls(
subscription_topic: impl Into<Option<String>>,
gmail_url: String,
people_url: String,
jwks_url: String,
audience: String,
) -> Self {
Self {
inner: reqwest::Client::builder()
.timeout(REQUEST_TIMEOUT)
.connect_timeout(CONNECT_TIMEOUT)
.build()
.expect("Gmail HTTP client should initialize"),
send_client: reqwest::Client::builder()
.timeout(REQUEST_TIMEOUT)
.connect_timeout(CONNECT_TIMEOUT)
.retry(reqwest::retry::never())
.redirect(reqwest::redirect::Policy::none())
.build()
.expect("Gmail send HTTP client should initialize"),
base_url: gmail_url.trim_end_matches('/').to_string(),
certs_url: jwks_url,
contacts_url: people_url.trim_end_matches('/').to_string(),
audience,
subscription_topic: subscription_topic.into(),
}
}
/// Lists the num_threads most recent threads for the user, optionally
/// filtered to threads carrying all of the given Gmail label ids
/// (an empty slice applies no filter).
#[tracing::instrument(skip(self, access_token), err)]
pub async fn list_threads(
&self,
access_token: &str,
num_threads: u32,
next_page_token: Option<&str>,
label_ids: &[&str],
) -> Result<ListThreadsResponse, GmailApiHttpError> {
threads::list_threads(self, access_token, num_threads, next_page_token, label_ids).await
}
/// Lists the `num_messages` most recent message provider ids for the user,
/// optionally filtered to messages carrying all of the given Gmail label
/// ids (an empty slice applies no filter). Capped at 500 by the Gmail API.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn list_messages(
&self,
access_token: &str,
num_messages: u32,
label_ids: &[&str],
) -> Result<Vec<String>, GmailApiHttpError> {
list_messages(self, access_token, num_messages, label_ids).await
}
// Returns a list containing the message ids belonging to the thread.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_message_ids_for_thread(
&self,
access_token: &str,
thread_id: &str,
) -> Result<Vec<String>, GmailApiHttpError> {
threads::get_message_ids_for_thread(self, access_token, thread_id).await
}
/// Fetches a single thread and its messages from Gmail.
/// Returns a raw Gmail ThreadResource - callers should map to service layer structs.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_thread(
&self,
access_token: &str,
thread_id: &str,
) -> Result<ThreadResource, GmailApiHttpError> {
get_thread(self, access_token, thread_id).await
}
/// Gets one page of the changes to a user's inbox since `start_history_id`.
/// Pass the previous page's `next_page_token` to continue. Returns the raw
/// HistoryListResponse; callers map it to inbox changes.
#[tracing::instrument(skip(self, access_token, page_token), err)]
pub async fn get_history_page(
&self,
access_token: &str,
start_history_id: &str,
page_token: Option<&str>,
) -> Result<HistoryListResponse, GmailApiHttpError> {
history::get_history_page(self, access_token, start_history_id, page_token).await
}
/// Fetches the user's raw Gmail profile.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_profile(
&self,
access_token: &str,
) -> Result<GmailUserProfile, GmailApiHttpError> {
profile::get_profile(self, access_token).await
}
/// Fetches Google's public JWKS keys used for verifying OAuth 2.0 tokens.
#[tracing::instrument(skip(self), err)]
pub async fn get_google_public_keys(&self) -> Result<GooglePublicKeys, GmailApiHttpError> {
fetch_google_public_keys(self).await
}
/// Verifies a Google JWT token against the provided public keys
/// Validates the token's signature, issuer, audience, and expiration time
#[tracing::instrument(skip(self, token, public_keys), err)]
pub fn verify_google_token(
&self,
token: &str,
public_keys: KeyMap,
) -> std::result::Result<GoogleJwtClaims, JwtVerificationError> {
verify_google_jwt(self, token, public_keys)
}
/// Registers a push notification watch on the user's inbox
/// This will cause notifications to be sent to the subscription_topic
#[tracing::instrument(skip(self, access_token), err)]
pub async fn register_watch(
&self,
access_token: &str,
) -> Result<models_email::gmail::history::WatchResponse, GmailApiHttpError> {
watch::register_watch(self, access_token).await
}
/// Stops push notifications by revoking the notification watch
#[tracing::instrument(skip(self, access_token), err)]
pub async fn stop_watch(&self, access_token: &str) -> Result<(), GmailApiHttpError> {
watch::stop_watch(self, access_token).await
}
/// Adds and removes labels according to the provided lists
#[tracing::instrument(
skip(self, access_token),
fields(provider_message_id = %provider_message_id),
err
)]
pub async fn modify_message_labels(
&self,
access_token: &str,
provider_message_id: &str,
label_ids_to_add: &[String],
label_ids_to_remove: &[String],
) -> Result<(), GmailApiHttpError> {
labels::modify_message_labels(
self,
access_token,
provider_message_id,
label_ids_to_add,
label_ids_to_remove,
)
.await
}
/// Adds and removes labels on many messages in one request (at most
/// [`models_email::gmail::gmail_ops::MAX_BATCH_MODIFY_MESSAGES`] ids).
#[tracing::instrument(
skip(self, access_token, provider_message_ids),
fields(message_count = provider_message_ids.len()),
err
)]
pub async fn batch_modify_message_labels(
&self,
access_token: &str,
provider_message_ids: &[String],
label_ids_to_add: &[String],
label_ids_to_remove: &[String],
) -> Result<(), GmailApiHttpError> {
labels::batch_modify_message_labels(
self,
access_token,
provider_message_ids,
label_ids_to_add,
label_ids_to_remove,
)
.await
}
/// Fetches a specific message from Gmail by its provider ID.
/// Returns raw Gmail MessageResource - callers should map to service layer structs.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_message(
&self,
access_token: &str,
message_provider_id: &str,
) -> Result<Option<MessageResource>, GmailApiHttpError> {
get_message(self, access_token, message_provider_id).await
}
/// Fetches a message's original RFC 822 bytes, or `None` when Gmail no
/// longer has it.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_raw_message(
&self,
access_token: &str,
message_provider_id: &str,
) -> Result<Option<Vec<u8>>, GmailApiHttpError> {
messages::get_raw_message(self, access_token, message_provider_id).await
}
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_message_label_ids(
&self,
access_token: &str,
message_provider_id: &str,
) -> Result<Option<Vec<String>>, GmailApiHttpError> {
get_message_label_ids(self, access_token, message_provider_id).await
}
/// Sends prepared MIME bytes and returns Gmail's provider identifiers.
#[tracing::instrument(skip(self, access_token, mime), err)]
pub async fn send_message(
&self,
access_token: &str,
mime: &[u8],
thread_id: Option<&str>,
) -> Result<models_email::gmail::SentMessageResource, GmailApiHttpError> {
messages::send_message(self, access_token, mime, thread_id).await
}
/// Looks for a unique sent message by its RFC 5322 Message-ID, including trash.
#[tracing::instrument(skip(self, access_token, message_id), err)]
pub async fn find_sent_message(
&self,
access_token: &str,
message_id: &str,
) -> Result<Option<models_email::gmail::SentMessageResource>, GmailApiHttpError> {
messages::find_sent_message(self, access_token, message_id).await
}
/// Fetches an attachment from Gmail by its provider ID
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_attachment_data(
&self,
access_token: &str,
message_id: &str,
attachment_id: &str,
) -> Result<Vec<u8>, GmailApiHttpError> {
attachments::get_attachment_data(self, access_token, message_id, attachment_id).await
}
/// Fetches user's Gmail labels
#[tracing::instrument(skip(self, access_token), err)]
pub async fn fetch_user_labels(
&self,
access_token: &str,
) -> Result<Vec<GmailLabel>, GmailApiHttpError> {
labels::fetch_user_labels(self, access_token).await
}
/// Creates a new Gmail label from a raw Gmail label request.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn create_label(
&self,
access_token: &str,
request: &GmailLabel,
) -> Result<GmailLabel, GmailApiHttpError> {
labels::create_label(self, access_token, request).await
}
/// Deletes a Gmail label by its ID.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn delete_label(
&self,
access_token: &str,
label_id: &str,
) -> Result<(), GmailApiHttpError> {
labels::delete_gmail_label(self, access_token, label_id).await
}
/// Fetches the user's own contact information.
/// Returns raw Gmail PersonResource - callers should map to service layer Contact.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn get_self_contact(
&self,
access_token: &str,
) -> Result<PersonResource, GmailApiHttpError> {
get_self_connection(self, access_token).await
}
/// Fetches one page of the user's main contacts. Pass the previous page's
/// `next_page_token` to continue; the last page carries the sync token for
/// future incremental updates. Callers map the people to service contacts.
/// Failures log at WARN: expired sync tokens and missing contacts scopes are routine.
#[tracing::instrument(skip(self, access_token, sync_token, page_token), err(level = "warn"))]
pub async fn get_contacts_page(
&self,
access_token: &str,
sync_token: Option<&str>,
page_token: Option<&str>,
) -> Result<ConnectionsResponse, GmailApiHttpError> {
contacts::get_connections_page(self, access_token, sync_token, page_token).await
}
/// Fetches one page of the user's "Other Contacts", typically created from
/// interactions. Paging and sync tokens work as in [`Self::get_contacts_page`].
/// Failures log at WARN: expired sync tokens and missing contacts scopes are routine.
#[tracing::instrument(skip(self, access_token, sync_token, page_token), err(level = "warn"))]
pub async fn get_other_contacts_page(
&self,
access_token: &str,
sync_token: Option<&str>,
page_token: Option<&str>,
) -> Result<OtherContactsResponse, GmailApiHttpError> {
contacts::get_other_contacts_page(self, access_token, sync_token, page_token).await
}
/// Creates a new Gmail filter.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn create_filter(
&self,
access_token: &str,
filter: Filter,
) -> Result<Filter, GmailApiHttpError> {
filters::create_filter(self, access_token, filter).await
}
/// Lists all filters for the user.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn list_filters(&self, access_token: &str) -> Result<Vec<Filter>, GmailApiHttpError> {
filters::list_filters(self, access_token).await
}
/// Deletes a filter by ID.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn delete_filter(
&self,
access_token: &str,
filter_id: &str,
) -> Result<(), GmailApiHttpError> {
filters::delete_filter(self, access_token, filter_id).await
}
/// Lists all sendAs aliases for the user, including their signatures.
#[tracing::instrument(skip(self, access_token), err)]
pub async fn list_send_as(
&self,
access_token: &str,
) -> Result<models_email::gmail::ListSendAsResponse, GmailApiHttpError> {
send_as::list_send_as(self, access_token).await
}
}