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

For code examples, see the Tool calling guide and Provider examples.

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
add_subscriber_tags
disable_webview
email_list_uuid
stringRequired
fields
html
mailable_class
name
stringRequired
schedule_at
segment_uuid
template_uuid
utm_tags

Action Response

data
objectRequired
error
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
allowed_form_subscription_tags
automation_mailer
campaign_mailer
campaigns_feed_enabled
confirmation_mail
confirmation_mail_content
confirmation_mail_subject
default_from_email
stringRequired
default_from_name
default_reply_to_email
default_reply_to_name
name
stringRequired
redirect_after_already_subscribed
redirect_after_subscribed
redirect_after_subscription_pending
redirect_after_unsubscribed
report_campaign_sent
report_campaign_summary
report_email_list_summary
report_recipients
requires_confirmation
transactional_mailer

Action Response

data
objectRequired
error
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

Action Response

data
objectRequired
error
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

Action Response

data
objectRequired
error
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
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
name
stringRequired
structured_html

Action Response

data
objectRequired
error
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
cc
html
name
stringRequired
store_mail
structured_html
subject
to

Action Response

data
objectRequired
error
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
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
stringRequired

Action Response

data
objectRequired
error
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
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
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
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
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
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
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
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
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
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
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]
filter[emailList.uuid]
filter[email_list_id]
filter[search]
filter[status]
page
sort

Action Response

data
arrayRequired
error
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
campaign_uuid
page
sort
subscriber_uuid
transactional_mail_log_item_uuid

Action Response

data
arrayRequired
error
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

Action Response

data
arrayRequired
error
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]
filter[search]
page
sort

Action Response

data
arrayRequired
error
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

Action Response

data
arrayRequired
error
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]
page
sort

Action Response

data
arrayRequired
error
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]
page
sort

Action Response

data
arrayRequired
error
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]
filter[search]
page
sort

Action Response

data
arrayRequired
error
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
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
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
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
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
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
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]
page
sort

Action Response

data
arrayRequired
error
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
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
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
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
first_name
last_name
skip_confirmation
strict
tags

Action Response

data
objectRequired
error
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
stringRequired

Action Response

data
objectRequired
error
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
add_subscriber_tags
content
disable_webview
email_list_uuid
stringRequired
fields
from_email
from_name
html
mailable_class
name
stringRequired
schedule_at
segment_uuid
subject
template_uuid
utm_tags
uuid
stringRequired

Action Response

data
objectRequired
error
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
allowed_form_subscription_tags
automation_mailer
campaign_mailer
campaigns_feed_enabled
confirmation_mail
confirmation_mail_content
confirmation_mail_subject
default_from_email
stringRequired
default_from_name
default_reply_to_email
default_reply_to_name
name
stringRequired
redirect_after_already_subscribed
redirect_after_subscribed
redirect_after_subscription_pending
redirect_after_unsubscribed
report_campaign_sent
report_campaign_summary
report_email_list_summary
report_recipients
requires_confirmation
transactional_mailer
uuid
stringRequired

Action Response

data
objectRequired
error
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
email
stringRequired
extra_attributes
first_name
last_name
subscriber_uuid
stringRequired
tags

Action Response

data
objectRequired
error
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
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

Action Response

data
objectRequired
error
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
name
stringRequired
structured_html
uuid
stringRequired

Action Response

data
objectRequired
error
successful
booleanRequired