API:Email:New

API » Create Contact Email Message

Base URL

https://app.callproof.com

Endpoint

/api/contact/email/messages/new/

Purpose

Creates and stores an email message associated with a contact through a CallProof email account. Use this to import or record an email conversation so it appears in the contact’s email history.

HTTP Method

POST

Headers

Header	Required	Description
Content-Type	Yes	Must be application/json.

Security

• Yes – Requires a valid API key and secret with permission to create contacts. Credentials are sent in the request body.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

Parameter	Type	Required	Description
api_key	object	Yes	Authentication credentials object.
api_key.key	string	Yes	Public API key assigned to your CallProof account.
api_key.secret	string	Yes	Private API secret paired with the API key.
message_data	object	Yes	Email message payload.
message_data.to_email_ids	array or string	Yes	Recipient email address(es).
message_data.from	string	Yes	Sender email address.
message_data.sent_date	datetime string	Yes	Date and time the email was sent.
message_data.subject	string	Yes	Email subject line. Maximum 255 characters.
message_data.body	object	Yes	Email body content.
message_data.body.content_type	string	Yes	Content type of the body (for example, text/plain or text/html).
message_data.body.content	string	Yes	Body content of the email.
message_data.message_id	string	Yes	Unique message identifier. Must not already exist for the same email account user.
message_data.account_id	integer	Yes	Email account identifier used to store the message.
message_data.has_attachments	integer	No	Indicates whether the message has attachments. Defaults to 0 if omitted.

cURL Example

curl -X POST "https://app.callproof.com/api/contact/email/messages/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "message_data": {
      "to_email_ids": ["john@acme.com"],
      "from": "rep@example.com",
      "sent_date": "2024-06-15 14:30:00",
      "subject": "Follow-up on proposal",
      "body": {
        "content_type": "text/plain",
        "content": "Hi John, following up on our proposal."
      },
      "message_id": "<unique-message-id@example.com>",
      "account_id": 101,
      "has_attachments": 0
    }
  }'

Successful Response (200)

Indicates the email message was stored successfully. The response returns the saved message details.

Field	Type	Description
results	object	Saved email message details.
results.email_message_id	integer	Unique identifier for the email message.
results.rep	object or null	Profile of the sales representative associated with the message.
results.contact	string	Display name of the associated contact.
results.contact_id	integer	Unique identifier of the associated contact.
results.contact_company_name	string	Name of the company associated with the contact.
results.inbox	string	1 if the message is inbound; 0 if outbound.
results.subject	string	Email subject line.
results.has_files	string	1 if the message has attachments; otherwise 0.
results.files	array	Attachments associated with the email message.
results.send_date	string	Date and time the email was sent (YYYY-MM-DD HH:MM:SS).
results.created	string	Date and time the email record was created (YYYY-MM-DD HH:MM:SS).
errors	object	Empty object when the request succeeds.
code	integer	HTTP-style status value; 200 on success.

Example response:

{
  "results": {
    "email_message_id": 9001,
    "rep": {
      "id": 123,
      "email": "rep@example.com",
      "user_id": 456,
      "name": "Jane Smith",
      "title": "Account Executive",
      "updated": "2024-06-01 10:00:00"
    },
    "contact": "John Doe",
    "contact_id": 789,
    "contact_company_name": "Acme Corp",
    "inbox": "0",
    "subject": "Follow-up on proposal",
    "has_files": "0",
    "files": [],
    "send_date": "2024-06-15 14:30:00",
    "created": "2024-06-15 14:31:00"
  },
  "errors": {},
  "code": 200
}

Notes

• All of the following are required: recipient address(es), sender address, sent date, subject, body content, message ID, and email account ID.
• The body must include both content_type and content.
• message_id must be unique for the email account user. Duplicate message IDs are rejected.
• The email account ID must refer to a valid email account.
• The message is associated with a contact based on the email account and recipient/sender details. If no matching contact or user can be determined, the message is not saved.
• Field-level validation failures typically return HTTP 200 with details in the errors object and an empty results value.
• Invalid JSON in the request body returns HTTP 400.
• has_attachments is optional and defaults to 0 when omitted.

Error Responses

Status Code	Meaning
200	Validation issue – One or more required fields are missing/invalid, the message ID already exists, or the message could not be associated with a contact/user.
400	Bad Request – The JSON payload is invalid or required message data is missing.
401	Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create contacts.
405	Method Not Allowed – A method other than POST was used.
500	Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

400 response body example:

{
  "results": [],
  "errors": ["Invalid json data"],
  "code": 400
}

200 validation response examples:

{
  "results": [],
  "errors": {
    "to_email_ids": ["To email id required"],
    "subject": ["Subject required"]
  },
  "code": 200
}

{
  "results": [],
  "errors": {
    "message_id": ["Already have this message"]
  },
  "code": 200
}

{
  "results": [],
  "errors": {
    "message_id": ["No contact or user found. Message not saved."]
  },
  "code": 200
}

401 response body example:

{
  "results": [],
  "errors": ["Invalid API Key"],
  "code": 401
}

405 response body example:

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}