Envío usando HTTP

La API HTTP permite enviar un contenido a uno o varios destinatarios con un sólo POST, utilizar variables de reemplazo para personalizarlos, e incluir etiquetas y atributos para su seguimiento.

SERVICIO DISCONTINUADO

La API de envíos transaccionales ya no está disponible para nuevas suscripciones.

Para las suscripciones activas, el servicio será discontinuado en su totalidad el día 1/3/2026.

Ejemplo básico

Empecemos por el ejemplo más sencillo posible:

curl -X POST \
  https://transactional.myperfit.com/v1/mail/send \
  -H 'Authorization: MI_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": { "email": "[email protected]" },
    "subject": "Asunto de prueba",
    "content": {"html": "<h1>Funciona! 💪</h1>"},
    "recipients": [{"to": {"email": "[email protected]"}}]
}'

Ejemplo usando una plantilla

Otra forma de indicar el contenido es utilizando una plantilla diseñada en la aplicación web, donde ya incluyen el remitente asunto y contenido.

curl -X POST \
  https://transactional.myperfit.com/v1/mail/send \
  -H 'Authorization: MI_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": "etpl_efd23wnfo23edsoirsnde",
    "recipients": [{"to": {"email": "[email protected]"}}]
}'

/mail/send

POST https://transactional.myperfit.com/v1/mail/send

Este endpoint permite encolar para su envío uno o varios emails que compartan el mismo contenido. Es posible enviar a hasta 1000 destinatarios (recipients) en un mismo request. El content, subject y headers pueden ser personalizados utilizando etiquetas de reemplazo del estilo ${object.key}.

Headers

Name	Type	Description
Authorization	string	Bearer API_KEY

Request Body

Name	Type	Description
Body	object	Cuerpo del mensaje en formato JSON

202 En caso de aceptar el pedido de envío.

{
    "success": true,
    "data": ""
}

Estructura del mensaje

Los únicos parámetros requeridos del body son: from.email, subject, content (al menos uno: html o text) y recipients (al menos uno, incluyendo al menos to.email).

• from: Object, requerido. Email y nombre del remitente.

  • email: String, requerido.

  • name: String, opcional.

• reply_to: Object, opcional. Dirección y nombre de respuesta.

  • email: String, requerido.

  • name: String, opcional.

• subject: String, requerido, max 200 chars. Asunto del correo.

• content: Object, requerido. Se debe indicar al menos un tipo.

  • html: String, opcional, max 300KB. Contenido de tipo text/html.

  • text: String, opcional, max 300KB. Contenido de tipo text/plain.

• template_id: String, opcional. El id de la plantilla a utilizar, en lugar de indicar el content. En caso de usar una plantilla, dejan de ser requeridos los campos from, reply_to, subject y content. En caso de indicar alguno de ellos, sus valores reemplazarán a los definidos en la plantilla.

• attachments: Array de objects, opcional.

  • file_name: String, requerido. Nombre del archivo adjunto.

  • mime_type: String, requerido. Tipo mime del archivo adjunto.

  • data: String, requerido. Contenido del archivo adjunto en base64.

• headers: Object, opcional. Mapa string-string con headers adicionales a incluir.

• recipients: Array de objetos, requerido. Debe contener al menos un elemento.

  • to: Object, requerido. Email y nombre del destinatario.

    • email: String, requerido.

    • name: String, opcional.

  • cc: Array de objects, opcional. Listado de destinatarios en copia.

    • email: String, requerido.

    • name: String, opcional

  • bcc: Array de objects, opcional. Misma estructura que el cc. Listado de destinatarios en copia oculta.

  • substitutions: Object, opcional. Modelo de reemplazo asociado a este destinatario.

  • custom_args: Object, opcional. Mapa string-string con información de identificación y seguimiento. Se informarán junto con los eventos de monitoreo.

  • tags: Array de strings, opcional. Etiquetas de identificación y seguimiento de este batch. Se informarán junto con los eventos de monitoreo.

• substitutions: Object, opcional. Modelo de reemplazo asociado a todo el batch.

• tracking: Object, opcional.

  • open: Object, opcional.

    • enable: Boolean, opcional, default: true. Activar monitoreo de aperturas.

  • click: Object, opcional.

    • enable: Boolean, opcional, default: true Activar monitoreo de clicks.

  • ganalytics: Object, opcional. Códigos de seguimiento para Google Analytics.

    • utm_source: String, opcional.

    • utm_medium: String, opcional.

    • utm_campaign: String, opcional.

    • utm_content: String, opcional.

    • utm_term: String, opcional.

• batch_code: String, opcional. Identificador alfanumérico (se limpan todos los caracteres que no sean [a-z0-9]).

• tags: Array de strings, opcional. Etiquetas de identificación y seguimiento de este batch. Se informarán junto con los eventos de monitoreo.

• launch_date: Fecha. Posponer el envío de este batch hasta la fecha y hora indicadas. Si no se indica se envía en forma inmediata.

Este objeto JSON incluye todas las opciones mencionadas.

{
	"from": {
		"email": "[email protected]", 
		"name": "Diego"
	},
	"reply_to": {
		"email": "[email protected]", 
		"name": "Diego"
	},
	"subject": "Hola ${contact.first_name}, este es el asunto",
	"content": {
		"html": "<!DOCTYPE ...><html><body><h1>Hola mundo!</h1></body></html>",
		"text": "Contenido de tipo texto"
	},
	"headers": {
		"X-My-Header": "my custom header value" 
	},
	"recipients" : [
		{
			"to": { 
				"email": "[email protected]",
				"name": "Nombre Recipient"
			},
			"cc": [ 
				{ 
					"email": "[email protected]",
					"name": "Nombre CC1"
				},
				{ 
					"email": "[email protected]",
					"name": "Nombre CC2"
				}				
			],
			"bcc": [ 
				{ 
					"email": "[email protected]",
					"name": "Nombre BCC1"
				},
				{ 
					"email": "[email protected]",
					"name": "Nombre BCC2"
				},				
			],
			"substitutions": {
				"contact": {
					"email": "[email protected]",
					"name": "Diego",
					"gender": "M",
					"age": 35,
					"ciudad": "Buenos Aires",
				}
			},
			"custom_args": {
				"internal_id": "43231312",
				"other_attr": "1234"
			},
			"tags": ["cliente frecuente"]
		}
	],
	"substitutions": {
		"account": {
			"business_name": "Perfit",
			"address": "San Nicolas 3940, CABA, Argentina",
		}
	},
	"attachments": [
  	{
  		"file_name": "file.png",
	    "mime_type": "image/png",
    	"data": "base64data"
    }
  ],     
	"tracking": { 
		"open": { 
			"enable": true 
		},
		"click": { 
			"enable": true
		},
		"ganalytics": {
			"utm_source": "Perfit",
			"utm_medium": "email",
			"utm_campaign": "my campaign"
		}
	},
	"batch_code": "mycampaign1234",
	"tags": ["electro"],
	"launch_date": "2019-08-20T13:30:00Z",
}

Cuando es necesario hacer un gran número de requests, es altamente recomendable mantener las conexiones HTTP abiertas usando keep-alive. Esto evita todo el overhead que se introduce al establecer las conecciones TCP. En las pruebas realizadas se vieron incrementos de ~5x en los requests por segundo alcanzados.