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.
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]"}}]
}'
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]"}}]
}'
post
https://transactional.myperfit.com/v1
/mail/send
/mail/send
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 tipotext/html
.text
: String, opcional, max 300KB. Contenido de tipotext/plain
.
template_id
: String, opcional. El id de la plantilla a utilizar, en lugar de indicar elcontent.
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.
Última actualización 2yr ago