mailerpress/create-contact creates a single contact with an email address, an optional name, and optional list, tag and custom-field assignments.
Behaviour depends on the site’s opt-in setting. A double-opt-in install sends a confirmation email and leaves the contact pending until they click; a single-opt-in install subscribes them immediately.
At a glance
| Ability | mailerpress/create-contact |
| Toolset | MailerPress — toolset/mailerpress |
| Group | MailerPress › Contacts |
| Requires | AcrossAI Pro, plus MailerPress active on the site |
| Capability | manage_options |
| Safety | Writes data |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Pro 0.9.16 and later |
How it works
That difference is consequential rather than cosmetic. On a double-opt-in site a created contact receives a confirmation email immediately — so creating contacts programmatically sends mail to those people, whether or not anybody intended it.
And until they click, they are pending and receive nothing. A bulk creation on a double-opt-in site produces a list of people who have been emailed once and cannot be emailed again.
Assigning lists and tags at creation saves a second call and, more importantly, means the contact is targetable immediately. A contact created with no list is subscribed and unreachable by list-targeted campaigns.
Custom-field values can be set here too, using keys from mailerpress/list-free-custom-fields or the Pro equivalent.
A duplicate email is an error. mailerpress/check-email-validity first.
Not idempotent.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
email | string | Yes | The email address. Must not already exist. |
first_name | string | No | First name. |
last_name | string | No | Last name. |
lists | array | No | List IDs to join. |
tags | array | No | Tag IDs to apply. |
custom_fields | object | No | Custom-field values by key. |
What comes back
| Name | Type | What it is |
|---|---|---|
contact | object | The created contact. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Add this person to the newsletter list.
It resolves to one call:
{
"ability": "mailerpress/create-contact",
"parameters": {
"email": "sam@example.com",
"first_name": "Sam",
"lists": [3]
}
}Worth knowing
- On a double-opt-in site this sends a confirmation email immediately.
- Pending contacts receive nothing until they click.
- A contact with no list is unreachable by list-targeted campaigns.
- A duplicate email is an error, not a merge.
Related abilities
- MailerPress Check Email Validity — avoid the duplicate error
- MailerPress Send Confirmation Email — resend to a pending contact
- MailerPress Import Contacts — the bulk path
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category