GrupoMail API

Welcome to the official Grupo Mail API documentation. Our RESTful API allows partners and clients to seamlessly interact with their form records in a centralized manner. You can extract leads, assign statuses, manage user access, and maintain full control over your data directly from your own applications.

Authentication

All endpoints in the Grupo Mail API require authentication using an API Key. You must include this key in the headers of every request using the Bearer token format.

Authorization: Bearer YOUR_API_KEY

Security Note: Keep your API keys secure. Do not share them in publicly accessible areas such as GitHub, client-side code, etc.

Common Errors

The API uses standard HTTP status codes to indicate the success or failure of an API request. The error structures below apply across all endpoints.

Code: {{ error.code }}

No endpoints found

Try adjusting your search query.

API Services

No additional parameters required.

{{ param.name }} {{ param.type }}

{{ param.description }}

Success Response

Code 200 OK

{{ endpoint.curl }}

WordPress Forms Integration

GrupoMail allows you to receive data from external forms via an HTTP POST endpoint. You can easily integrate your WordPress forms by utilizing hooks provided by popular form plugins. Currently, we actively support workflows for WPForms and Contact Form 7.

1. Endpoint URL & Request Format

Each form within GrupoMail possesses a unique endpoint. When a user submits a form on your WordPress site, your server must send the collected data to this endpoint. The endpoint expects data in the application/x-www-form-urlencoded format.

POST https://{domain}.grupomail.com/sendataform/{form_token}

Example Payload

5df44e9186451a14edba68462f44f4f9=Juan Pérez
[email protected]
71c083ee0d67a4ebba47fd70b713afba=8095550000
ip=190.80.10.1

2. Capture User IP

We strongly recommend passing the user's IP address to the ip parameter. Add this helper function to your WordPress functions.php file.

function grupomail_get_ip() {
    if (!empty($_SERVER['HTTP_CLIENT_IP'])) {
        return $_SERVER['HTTP_CLIENT_IP'];
    }
    if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
        $lista = explode(',', $_SERVER['HTTP_X_FORWARDED_FOR']);
        return trim($lista[0]);
    }
    return $_SERVER['REMOTE_ADDR'] ?? '';
}

WPForms allows you to execute custom code right after a successful form submission by hooking into wpforms_process_complete or specifically wpforms_process_complete_{FORM_ID}.

add_action('wpforms_process_complete_7349', 'send_to_grupomail', 10, 4);

function send_to_grupomail($fields, $entry, $form_data, $entry_id) {

    $body = [
        '5df44e9186451a14edba68462f44f4f9' => $fields['1']['value'], // Name field ID in WPForms
        '7f23b1e685aaa9d86886668e1ce76506' => $fields['5']['value'], // Email field ID in WPForms
        'ip' => grupomail_get_ip()
    ];

    $response = wp_remote_post(
        'https://example.grupomail.com/sendataform/a9f3c7e12d6...',
        [
            'method' => 'POST',
            'body'   => $body
        ]
    );
    
    if (is_wp_error($response)) {
        error_log('GrupoMail error: ' . $response->get_error_message());
    }
}

Contact Form 7 allows you to intercept the form submission right before or after the email is sent using the wpcf7_mail_sent hook.

add_action('wpcf7_mail_sent', 'send_to_grupomail');

function send_to_grupomail($contact_form) {

    $submission = WPCF7_Submission::get_instance();

    if (!$submission) {
        return;
    }

    $data = $submission->get_posted_data();

    $body = [
        '5df44e9186451a14edba68462f44f4f9' => $data['text-name'], // CF7 field tag
        '7f23b1e685aaa9d86886668e1ce76506' => $data['email'],     // CF7 field tag
        'ip' => grupomail_get_ip()
    ];

    $response = wp_remote_post(
        'https://example.grupomail.com/sendataform/a9f3c7e12d6...',
        [
            'method' => 'POST',
            'body'   => $body
        ]
    );
    
    if (is_wp_error($response)) {
        error_log('GrupoMail error: ' . $response->get_error_message());
    }
}

Handling Checkboxes/Lists

Some plugins return multiple selections (like Checkboxes) as values separated by newlines (\n). To ensure GrupoMail registers them correctly, convert them to a comma-separated string:

// Given: "Product A\nProduct B\nProduct C"
$productos = explode("\n", $fields['6']['value']);
$productos_string = implode(', ', $productos);

// Result: "Product A, Product B, Product C"

Best Practices

• Sanitize data: Ensure all variables are properly sanitized before posting to prevent malicious injections.
• Validate emails: Verify that the email provided exists in the payload and is a valid address.
• Always send the IP: Sending the IP address assists GrupoMail in mapping geographic location and preventing spam.
• Handle connection errors: Use is_wp_error() to log connection drops silently without affecting user experience.
• Backend logic only: Never expose the form token endpoint inside Frontend JavaScript. Use PHP hooks.