Run Action
Queue an open, click, unsubscribe, reply, ARF, out-of-office, or Release action.
Queue an open, click, unsubscribe, reply, ARF, out-of-office, or Release action.
Scope: email_testing.messages.write
Path Parameters
idstringrequiredThe ID of the captured message, for example d5949378-3069-4d8f-a8f3-6e5edf5d6060. You get it from List Messages or the message.received webhook. It isn't the email's Message-ID header.
Request Body
typestringrequiredThe action to run: open, click, unsubscribe, reply, arf (spam complaint), ooo (out-of-office reply), or release (send the message to a real address).
dataobjectoptionalOptions for the chosen action, listed in the table below. Some actions take none.
Any other top-level key returns 400 with <key> is not accepted. An unknown key in data returns 400 with data.<key> is not accepted. For open and unsubscribe, data may be omitted, null, or {}.
data fields by action type
| Action type | Accepted data fields |
|---|---|
open, unsubscribe | None. |
click | Optional url (string to click), urls (array of exact message URLs), or links ("all" or an array of link IDs from List Links). urls and links cannot be combined. With no selector, all listed links are clicked. |
reply, arf, ooo | None. Maileroo builds the recipient, subject, and body from the captured message. |
release | Required domain_id (integer) and to (string). See List Release Domains. |
Release domains must be non-sandbox domains with DKIM and SPF verified. The released message is sent through SMTP Relay and counts toward normal sending quota. Its From address uses the original sender's local part at the selected domain, or eight random lowercase hexadecimal characters if no original From address is available. Each account can release up to 50 messages per hour.
Headers
Idempotency-KeystringoptionalA unique value of your choice, such as a UUID, so you can safely retry an open, click, unsubscribe, reply, arf or ooo request. Sending the same key with the same body returns the original action instead of running it again.
Requests return 202 Accepted. For the action types listed above, reusing an Idempotency-Key with the same request returns the existing action; reusing it with a different request returns 409 Conflict.
Sample Request
curl -X POST "https://api.maileroo.com/v1/email-testing/messages/d5949378-3069-4d8f-a8f3-6e5edf5d6060/actions" \
-H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"type":"click","data":{"links":"all"}}'curl -X POST "https://api.maileroo.com/v1/email-testing/messages/d5949378-3069-4d8f-a8f3-6e5edf5d6060/actions" \
-H "Authorization: Bearer roo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"type":"release","data":{"domain_id":123,"to":"[email protected]"}}'Sample Response
The response is wrapped in a data object.
{
"data": {
"id": "2a8e74f9-aac3-43e8-855a-0b3d61e85744",
"message_id": "d5949378-3069-4d8f-a8f3-6e5edf5d6060",
"type": "click",
"status": "queued",
"created_at": "2025-01-01T12:00:00Z"
}
}Errors
400 Bad Request— invalid action type or options, or an unknown top-level ordatakey.403 Forbidden— simulated actions are not included in the account's plan.404 Not Found— the message does not exist or is not owned by the account.409 Conflict— the idempotency key is already associated with a different request.422 Unprocessable Entity— the action is unavailable for this message, or the Release domain/message is not eligible.429 Too Many Requests— an action limit was reached; Release is limited to 50 messages per account per hour.502 Bad Gateway— a Release was queued, but its action history could not be recorded.503 Service Unavailable— Email Testing or the action runner is unavailable.