Matchai Docs

Email a contactComing soon

Sends an email from Matchai to one of your contacts, in the account holder’s name, with up to three documents attached.

Coming soon. This is documented ahead of launch so you can plan your integration; it is not available yet.
POST
/emails

Coming soon. Sends an email from Matchai to one of your contacts, in the account holder’s name, with up to three documents attached. An email cannot be taken back once it is sent.

Final action. When the connection is set to Ask me, this call returns 202 with an approval_url and does nothing until the account holder approves it in Matchai; Matchai then performs it exactly as sent and sends approval.resolved. When the connection is set to Allowed, it runs straight away.

Spends Matchai Energy. Returns 402 without doing anything when the account does not have enough Energy, or when this connection reached the Energy limit the account holder set for it.

Scopes: messages:send

Pricing: Included with the connection, and spends Matchai Energy.

Authorization

headerAuthorizationBearer <matchai_<base62>>

A personal API key, sent as Authorization: Bearer matchai_…. Create keys in Matchai under Settings → Connectors → Advanced (for developers). A key starts with matchai_ followed by letters and digits, carries the scopes chosen when it was created, and can be revoked at any time. Keys reach only the account that created them: to serve other professionals, use Connect with Matchai.

Scope: messages:send

Header Parameters

Idempotency-Key?string

A unique string (a UUID works). Retrying with the same key within 24 hours returns the first response instead of acting twice. Reusing a key with a different body returns 409 idempotency_key_reused.

Length1 <= length <= 255

Request Body

application/json
  1. body

Addresses that bounced or complained are refused with 422 recipient_suppressed. A sign-off is added for you.

contact_id*string

The recipient. Only your contacts can be emailed.

Length1 <= length <= 64
subject*string

Exact subject line.

Length1 <= length <= 200
body*string

Exact body, plain text. No sign-off.

Length1 <= length <= 20000
document_ids?array<>

Attachments, 10 MB together at most.

Itemsitems <= 3
listing_id?string

A listing to link. It is linked only when it is published on your own site.

Length1 <= length <= 64

Response Body

The email.

application/json
  1. response

An email sent from Matchai to one of your contacts, in your name.

id*string

Email id.

Length1 <= length <= 64
contact_id*string

Recipient contact.

Length1 <= length <= 64
to*

The address itself is not returned.

subject*string

Subject.

listing_id?|

Linked listing.

Length1 <= length <= 64
document_ids?array<>

Attachments.

status*string
Value in"queued""sent""delivered""bounced""complained""failed"
created_at*string

Created.

Formatdate-time
sent_at?|

Handed over for delivery.

Formatdate-time
delivered_at?|

Delivered to the recipient’s mailbox.

Formatdate-time
Example Request
curl -X POST 'https://api.matchai.co/v1/emails' \  -H 'Idempotency-Key: 6f1d3c2a-0b7e-4f5a-9c8d-1e2f3a4b5c6d' \  -H 'Content-Type: application/json' \  -d '{  "contact_id": "string",  "subject": "string",  "body": "string"}'
Example Response
{  "id": "string",  "contact_id": "string",  "to": {    "display_name": "string"  },  "subject": "string",  "listing_id": "string",  "document_ids": [    "string"  ],  "status": "queued",  "created_at": "2019-08-24T14:15:22Z",  "sent_at": "2019-08-24T14:15:22Z",  "delivered_at": "2019-08-24T14:15:22Z"}