Mailcoach

Learn how to use Mailcoach with Composio

Overview

SLUG: MAILCOACH

Description

Mailcoach is an email marketing platform that allows users to manage email campaigns and subscriber lists efficiently.

Authentication Details

subdomain
stringRequired
generic_api_key
stringRequired

Connecting to Mailcoach

Create an auth config

Use the dashboard to create an auth config for the Mailcoach toolkit. This allows you to connect multiple Mailcoach accounts to Composio for agents to use.

1

Select App

Navigate to Mailcoach.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Mailcoach Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4mailcoach_auth_config_id = "ac_YOUR_MAILCOACH_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Mailcoach for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, mailcoach_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Mailcoach toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["MAILCOACH"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Add Mailcoach Campaign

Description

Tool to create a new mailcoach campaign. use when you need to send or schedule an email campaign to a specific list or segment.

Action Parameters

add_subscriber_link_tags
boolean
add_subscriber_tags
boolean
disable_webview
boolean
email_list_uuid
stringRequired
fields
object
html
string
mailable_class
string
name
stringRequired
schedule_at
string
segment_uuid
string
template_uuid
string
utm_tags
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Add Email List

Description

Tool to create a new email list. use when you need to manage and organize subscribers before sending campaigns. use after authentication.

Action Parameters

allow_form_subscriptions
boolean
allowed_form_subscription_tags
array
automation_mailer
string
campaign_mailer
string
campaigns_feed_enabled
boolean
confirmation_mail
string
confirmation_mail_content
string
confirmation_mail_subject
string
default_from_email
stringRequired
default_from_name
string
default_reply_to_email
string
default_reply_to_name
string
name
stringRequired
redirect_after_already_subscribed
string
redirect_after_subscribed
string
redirect_after_subscription_pending
string
redirect_after_unsubscribed
string
report_campaign_sent
boolean
report_campaign_summary
boolean
report_email_list_summary
boolean
report_recipients
string
requires_confirmation
boolean
transactional_mailer
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Add suppression

Description

Tool to add a suppression entry. use after detecting a bounce, spam complaint, or manual block.

Action Parameters

email
stringRequired
reason
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Add Tag to Email List

Description

Tool to create a new tag within a specific email list. use after confirming the email list exists.

Action Parameters

email_list_uuid
stringRequired
name
stringRequired
visible_in_preferences
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Add Tags to Subscriber

Description

Tool to add tags to a subscriber. use after retrieving a subscriber's uuid to segment them.

Action Parameters

subscriber_uuid
stringRequired
tags
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Add Template

Description

Tool to create a new email template. use after preparing template name and optional html content.

Action Parameters

html
string
name
stringRequired
structured_html
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Add Transactional Email Template

Description

Tool to create a new template that can be used for transactional emails.

Action Parameters

bcc
string
cc
string
html
string
name
stringRequired
store_mail
boolean
structured_html
string
subject
string
to
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Append to Subscriber Import

Description

Tool to append csv data to an existing subscriber import. use after retrieving a subscriber import when additional subscriber data needs to be added.

Action Parameters

import_uuid
stringRequired
subscribers_csv
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Confirm Subscriber

Description

Tool to confirm a subscriber’s subscription. use when finalizing the double opt-in process after they have provided subscriber details. example: "confirm subscriber with uuid 123e4567-e89b-12d3-a456-426614174000"

Action Parameters

subscriber_uuid
Required

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Subscriber Import

Description

Tool to create a new subscriber import. use when you have a prepared csv and want to upload it into an existing mailcoach email list after exporting or generating subscriber data.

Action Parameters

email_list_uuid
stringRequired
replace_tags
booleanRequired
subscribe_unsubscribed
booleanRequired
subscribers_csv
stringRequired
unsubscribe_others
booleanRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Campaign

Description

Tool to delete a campaign by uuid. use when you need to permanently remove a campaign after confirming its identifier.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Email List

Description

Tool to delete an email list by uuid. use when you need to permanently remove an email list after confirming its identifier.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Send

Description

Tool to delete a sent item by its uuid. use after confirming the send's uuid to permanently remove it.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Subscriber

Description

Tool to delete a subscriber by uuid. use when you need to permanently remove a subscriber from the system after verifying their uuid.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Subscriber Import

Description

Tool to delete a subscriber import by its uuid. use when you need to permanently remove a subscriber import after confirming its identifier.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Suppression

Description

Tool to delete a suppression entry by uuid. use when you need to permanently remove a suppression after confirming its identifier.

Action Parameters

suppression_uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Tag from Email List

Description

Tool to delete a tag from an email list. use when you need to permanently remove a tag after confirming its identifiers.

Action Parameters

email_list_uuid
stringRequired
uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Template

Description

Tool to delete a template by uuid. use when you need to permanently remove a template after confirming its uuid.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Transactional Mail

Description

Tool to delete a transactional mail by its uuid. use when you need to permanently remove a transactional mail after confirming its uuid.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get All Campaigns

Description

Tool to retrieve all campaigns. use when you need a paginated, sortable list of campaigns matching criteria.

Action Parameters

filter[contentItem.template.uuid]
string
filter[emailList.uuid]
string
filter[email_list_id]
string
filter[search]
string
filter[status]
string
page
integer
sort
string

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get All Sent Items

Description

Tool to retrieve all sent items. use when you need to list and filter sent items after delivery.

Action Parameters

automation_mail_uuid
string
campaign_uuid
string
page
integer
sort
string
subscriber_uuid
string
transactional_mail_log_item_uuid
string

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get All Subscriber Imports

Description

Tool to retrieve all subscriber imports. use when you need a paginated list of import jobs.

Action Parameters

page
integer

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get All Suppressions

Description

Tool to list all suppression entries. use when you need suppression uuids for further retrieval.

Action Parameters

filter[reason]
string
filter[search]
string
page
integer
sort
string

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get All Tags

Description

Tool to retrieve all tags for a specific email list. use after confirming the email list exists.

Action Parameters

email_list_uuid
stringRequired
page
integer

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get All Templates

Description

Tool to retrieve all templates. use when you need a paginated list of templates with optional search and sorting.

Action Parameters

filter[search]
string
page
integer
sort
string

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get All Transactional Email Templates

Description

Tool to retrieve all transactional email templates. use when you need a paginated list of transactional templates matching your criteria.

Action Parameters

filter[name]
string
page
integer
sort
string

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get Email Lists

Description

Tool to retrieve all email lists. use when you need to fetch a paginated list of email lists with optional filters.

Action Parameters

filter[name]
string
filter[search]
string
page
integer
sort
string

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get Specific Campaign

Description

Tool to retrieve details of a specific mailcoach campaign. use when you need the full campaign resource by its uuid.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Specific Email List

Description

Tool to retrieve a specific email list. use when you need to fetch details by uuid.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Specific Subscriber

Description

Tool to retrieve a specific subscriber. use when you need to fetch subscriber details by uuid.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Specific Suppression

Description

Tool to retrieve a specific suppression entry. use when you need to fetch suppression details by uuid or email.

Action Parameters

suppression_uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Specific Tag

Description

Tool to retrieve details of a specific tag. use when you need to fetch tag metadata after confirming the email list and tag uuids.

Action Parameters

email_list_uuid
stringRequired
uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Specific Template

Description

Tool to retrieve details of a specific template. use when you need template information by uuid.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Transactional Mails

Description

Tool to retrieve all transactional mail templates. use when you need a paginated list of transactional mails.

Action Parameters

filter[name]
string
page
integer
sort
string

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Remove Tags from Subscriber

Description

Tool to remove tags from a subscriber. use after retrieving a subscriber's uuid to adjust their segments.

Action Parameters

subscriber_uuid
stringRequired
tags
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Resend Subscriber Confirmation

Description

Tool to resend confirmation email to a subscriber. use when a subscriber hasn't confirmed and you need to resend the confirmation.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Start Subscriber Import

Description

Tool to start processing a subscriber import. use when you have a draft subscriber import ready to be processed.

Action Parameters

uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Subscribe To Email List

Description

Tool to add or update a subscriber in an email list. use when you have subscriber details and need to subscribe them to a specific list, optionally skipping confirmation or enforcing strict mode.

Action Parameters

email
stringRequired
email_list_uuid
stringRequired
extra_attributes
object
first_name
string
last_name
string
skip_confirmation
boolean
strict
boolean
tags
array

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Unsubscribe Subscriber

Description

Tool to unsubscribe a subscriber from an email list. use when removing a subscriber upon their request after confirming details. example: "unsubscribe subscriber with uuid 123e4567-e89b-12d3-a456-426614174000"

Action Parameters

subscriber_uuid
Required

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Campaign

Description

Tool to update an existing mailcoach campaign. use after identifying the campaign uuid when you need to modify campaign attributes such as name, schedule, or content.

Action Parameters

add_subscriber_link_tags
boolean
add_subscriber_tags
boolean
content
string
disable_webview
boolean
email_list_uuid
stringRequired
fields
object
from_email
string
from_name
string
html
string
mailable_class
string
name
stringRequired
schedule_at
string
segment_uuid
string
subject
string
template_uuid
string
utm_tags
boolean
uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Email List

Description

Tool to update an existing email list. use when you need to modify a list's configuration after verifying its uuid.

Action Parameters

allow_form_subscriptions
boolean
allowed_form_subscription_tags
array
automation_mailer
string
campaign_mailer
string
campaigns_feed_enabled
boolean
confirmation_mail
string
confirmation_mail_content
string
confirmation_mail_subject
string
default_from_email
stringRequired
default_from_name
string
default_reply_to_email
string
default_reply_to_name
string
name
stringRequired
redirect_after_already_subscribed
string
redirect_after_subscribed
string
redirect_after_subscription_pending
string
redirect_after_unsubscribed
string
report_campaign_sent
boolean
report_campaign_summary
boolean
report_email_list_summary
boolean
report_recipients
string
requires_confirmation
boolean
transactional_mailer
string
uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Subscriber

Description

Tool to update a subscriber. use when you need to modify subscriber details after creation.

Action Parameters

append_tags
boolean
email
stringRequired
extra_attributes
object
first_name
string
last_name
string
subscriber_uuid
stringRequired
tags
array

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Subscriber Import

Description

Tool to update an existing subscriber import. use when you need to modify a draft import before execution. import must be in draft status.

Action Parameters

email_list_uuid
stringRequired
import_uuid
stringRequired
replace_tags
booleanRequired
subscribe_unsubscribed
booleanRequired
subscribers_csv
stringRequired
unsubscribe_others
booleanRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Tag

Description

Tool to update an existing tag within an email list. use when you need to modify the name or visibility of a tag after verifying its existence.

Action Parameters

email_list_uuid
stringRequired
name
stringRequired
uuid
stringRequired
visible_in_preferences
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Template

Description

Tool to update an existing template's name or content. use when you need to modify a template's html or structured html by its uuid.

Action Parameters

html
string
name
stringRequired
structured_html
string
uuid
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired