Lewati ke konten utama

Memulai Menggunakan Mailtarget + Google Vertex AI

Berikan kemampuan kepada agen Vertex AI Anda untuk mengirim email secara otomatis.

P
Ditulis oleh Product Support
Diperbarui minggu ini

Prasyarat

  • Proyek Google Cloud dengan penagihan diaktifkan

  • Akun Mailtarget dengan akses API

  • API Vertex AI diaktifkan pada proyek GCP Anda

  • Python 3.10+ terinstall

  • Domain perusahaan yang Anda miliki (misalnya, yourcompany.com)

⚠️ Domain Perusahaan Diperlukan

Anda harus menggunakan domain perusahaan Anda sendiri untuk mengirim email (misalnya, [email protected]). Domain email gratis seperti Gmail, Yahoo, Outlook, atau penyedia email publik lainnya tidak diizinkan sebagai alamat pengirim.

Domain Anda dapat dihosting di penyedia mana pun — Google Workspace, Microsoft 365, Cloudflare, atau penyedia DNS lainnya. Selama Anda memiliki domain tersebut dan dapat mengkonfigurasi catatan DNS-nya, Anda siap untuk menggunakannya.

💡 Kami sangat menyarankan untuk menggunakan subdomain (misalnya, mail.yourcompany.com) atau domain khusus baru untuk pengiriman. Ini menjaga reputasi domain utama Anda tetap terisolasi dan memberi Anda lingkungan yang aman untuk pengujian.


  1. Siapkan Environment GCP Anda

    Install Google Cloud CLI dan lakukan autentikasi:

    # Install gcloud CLI (if not already installed) 
    # https://cloud.google.com/sdk/docs/install

    # Authenticate
    gcloud auth login
    gcloud auth application-default login

    # Set your project
    gcloud config set project YOUR_PROJECT_ID

    # Enable Vertex AI API gcloud services enable aiplatform.googleapis.com

  2. Dapatkan API Key Mailtarget Anda

    a. Masuk ke app.mailtarget.co

    b. Buka Configuration → API Key

    c. Klik Create API Key

    d. Salin Key-nya

    export MAILTARGET_API_KEY=your_api_key_here


  3. Install Dependensi

    pip install google-cloud-aiplatform requests

  4. Definisikan Mailtarget Tool

    Buat fungsi Python yang akan digunakan agen Vertex AI Anda untuk mengirim email:

    import requests
    import os

    def send_email(
    to_email: str,
    to_name: str,
    subject: str,
    body_html: str,
    body_text: str = ""
    ) -> dict:
    """Send an email via Mailtarget API.

    Args:
    to_email: Recipient email address.
    to_name: Recipient name.
    subject: Email subject line.
    body_html: HTML content of the email.
    body_text: Plain text fallback (optional).

    Returns:
    dict with transmissionId on success, or error details.
    """
    response = requests.post(
    "https://transmission.mailtarget.co/v1/layang/transmissions",
    headers={
    "Authorization": f"Bearer {os.environ['MAILTARGET_API_KEY']}",
    "Content-Type": "application/json"
    },
    json={
    "to": [{"email": to_email, "name": to_name}],
    "from": {
    "email": "[email protected]",
    "name": "Your Company"
    },
    "subject": subject,
    "bodyHtml": body_html,
    "bodyText": body_text,
    "optionsAttributes": {
    "openTracking": True,
    "clickTracking": True,
    "transactional": True
    }
    }
    )
    return response.json()

    Ganti [email protected] dan Your Company dengan domain pengirim dan nama perusahaan Anda yang telah diverifikasi.

  5. Buat Agen Vertex AI

    Hubungkan ini ke dalam agen Vertex AI menggunakan Agent Development Kit (ADK) atau LangChain:

    Opsi A: Menggunakan Google ADK

    from google.adk.agents import Agent

    agent = Agent(
    name="email_agent",
    model="gemini-2.0-flash",
    description="An agent that sends emails via Mailtarget.",
    instruction="""You are an email assistant. When asked to send
    an email, use the send_email tool. Write professional HTML
    emails with clean formatting. Always confirm the transmissionId
    after sending.""",
    tools=[send_email],
    )

    # Run the agent
    response = agent.run(
    "Send a welcome email to [email protected] (John Smith) "
    "with a friendly onboarding message."
    )
    print(response)

    Option B: Menggunakan LangChain

    from langchain_google_vertexai import ChatVertexAI
    from langchain.agents import AgentExecutor, create_tool_calling_agent
    from langchain_core.tools import tool
    from langchain_core.prompts import ChatPromptTemplate

    @tool
    def send_email(to_email: str, to_name: str, subject: str,
    body_html: str, body_text: str = "") -> dict:
    """Send an email via Mailtarget API."""
    import requests, os
    response = requests.post(
    "https://transmission.mailtarget.co/v1/layang/transmissions",
    headers={
    "Authorization": f"Bearer {os.environ['MAILTARGET_API_KEY']}",
    "Content-Type": "application/json"
    },
    json={
    "to": [{"email": to_email, "name": to_name}],
    "from": {"email": "[email protected]",
    "name": "Your Company"},
    "subject": subject,
    "bodyHtml": body_html,
    "bodyText": body_text,
    "optionsAttributes": {"openTracking": True,
    "clickTracking": True}
    }
    )
    return response.json()

    llm = ChatVertexAI(model="gemini-2.0-flash")

    prompt = ChatPromptTemplate.from_messages([
    ("system", "You are an email assistant. Use the send_email "
    "tool when asked to send emails."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
    ])

    agent = create_tool_calling_agent(llm, [send_email], prompt)
    executor = AgentExecutor(agent=agent, tools=[send_email])

    result = executor.invoke({
    "input": "Send a welcome email to [email protected] (John Smith) "
    "with a friendly onboarding message."
    })
    print(result["output"])

  6. Implementasi ke Vertex AI Agent Engine (Produksi)

    Untuk implementasi produksi, gunakan Vertex AI Agent Engine:

    import vertexai
    from vertexai import agent_engines

    vertexai.init(project="YOUR_PROJECT_ID", location="us-central1")

    # Deploy the agent
    remote_agent = agent_engines.create(
    agent_engine=agent,
    requirements=["requests"],
    display_name="Mailtarget Email Agent",
    )

    # Query the deployed agent
    session = remote_agent.create_session(user_id="user-1")
    response = remote_agent.stream_query(
    session=session,
    message="Send a test email to [email protected]"
    )
    for chunk in response:
    print(chunk)


🚀 Apa yang Baru Saja Anda Bangun

Agen Vertex AI Anda sekarang dapat secara otomatis:

  • Menulis konten email dalam gaya atau nada apa pun

  • Mendesain email HTML dengan format yang tepat

  • Mengirim melalui infrastruktur produksi Mailtarget

  • Melacak pembukaan dan klik secara otomatis

  • Menskalakan di runtime terkelola Google Cloud


Apa yang Terjadi di Balik Layar

  • Anda memberi tahu agen apa yang harus dikirim dan kepada siapa harus dikirim.

  • Vertex AI menulis konten, membangun HTML, dan memanggil alat Mailtarget.

  • Mailtarget menangani pengiriman, otentikasi (SPF/DKIM/DMARC), pelacakan, dan keandalan.

Lanjutan: Tambahkan Lebih Banyak Alat Mailtarget

Perluas agen Anda dengan kemampuan tambahan:

def list_sending_domains() -> dict:
"""List all verified sending domains in Mailtarget."""
response = requests.get(
"https://transmission.mailtarget.co/v1/domain/sending",
headers={"Authorization": f"Bearer {os.environ['MAILTARGET_API_KEY']}"}
)
return response.json()

def create_template(template_id: str, name: str, html: str) -> dict:
"""Create a reusable email template in Mailtarget."""
response = requests.post(
"https://transmission.mailtarget.co/v1/template",
headers={
"Authorization": f"Bearer {os.environ['MAILTARGET_API_KEY']}",
"Content-Type": "application/json"
},
json={"id": template_id, "name": name, "html": html}
)
return response.json()

def send_template_email(to_email: str, to_name: str,
subject: str, template_id: str,
substitution_data: dict) -> dict:
"""Send an email using a stored Mailtarget template."""
response = requests.post(
"https://transmission.mailtarget.co/v1/layang/transmissions",
headers={
"Authorization": f"Bearer {os.environ['MAILTARGET_API_KEY']}",
"Content-Type": "application/json"
},
json={
"to": [{"email": to_email, "name": to_name}],
"from": {"email": "[email protected]",
"name": "Your Company"},
"subject": subject,
"templateId": template_id,
"substitutionData": substitution_data
}
)
return response.json()

Tambahkan ini ke daftar alat agen Anda untuk kemampuan manajemen email yang lengkap.


Penyelesaian Masalah

Masalah

Perbaikan

401 Unauthorized

Periksa apakah Mailtarget API key sudah benar dan MAILTARGET_API_KEY sudah diatur

400 Bad Request

Verifikasi bahwa email pengirim menggunakan domain perusahaan yang terverifikasi

Email tidak sampai

Periksa folder spam; verifikasi catatan SPF/DKIM untuk domain Anda

Kesalahan izin Vertex AI

Pastikan aiplatform.googleapis.com diaktifkan dan Anda sudah terautentikasi

Agen tidak memanggil alat

Periksa docstring fungsi — Gemini menggunakannya untuk memutuskan kapan harus memanggil alat tersebut

Domain email gratis ditolak

Gunakan domain perusahaan Anda — Gmail, Yahoo, Outlook, dll. tidak diizinkan

Sumber

Apakah pertanyaan Anda terjawab?