Submit a Message passing the user fiscal_code in the request body
Description
This API makes it possible to send messages to a citizen identified by the fiscal code. Before sending a message, you must
check that the citizen is registered with IO and that the service can send communications to the citizen.
To use this API you must add to the call the header `Ocp-Apim-Subscription-Key` containing the [primary](../../function/publish-a-service/mandatory data/attributes.md#primary_key) or [secondary](../../function/publish-a-service/mandatory data/attributes.md#secondary_key) "use" key of the service chosen to send the message
fiscal_code*
| |
|---|
| Description | Fiscal code of the message recipient |
| Mandatory | Yes |
| Type | String |
| Example | AAAAAA00A00A000A |
time_to_live
**This parameter is deprecated.**
| |
|---|
| Description | Time expressed in seconds that specifies the message delivery retry time by IO; once this time has passed, no other push notification or forwarding email is produced |
| Mandatory | No |
| Default | 3600 |
| Type | Integer |
| Example | 3600 |
feature_level_type
| |
|---|
| Description | Indicates if the message is sent within the scope of a Premium subscription, or if it is to be considered a standard message |
| Mandatory | No |
| Default | STANDARD |
| Type | Enumerated string |
| Accepted values | STANDARD -> the message is considered a normal IO message ADVANCED -> additional advanced information is correlated with the message. This value can be specified only if you have a Premium subscription.
|
| Example | ADVANCED |
content ``*
subject ``*
| |
|---|
| Description | Subject of the message, whose length must be between 10 and 120 characters |
| Mandatory | Yes |
| Type | String |
| Example | Rinnova la tua carta d'identità |
If you are sending a **message with remote content**, refer to [#important-information-about-the-subject-title-of-the-message](../../function/send-a-message/send-a-message-remote-content.md#informazioni-importanti-circa-il-titolo-subject-del-messaggio "mention")
markdown ``*
| |
|---|
| Description | Text of the message in markdown format, whose length must be between 80 and 10000 characters |
| Mandatory | Yes |
| Type | String |
| Example | Gentile Mario,\n\nsiamo lieti di comunicarti che la tua **Carta di Identità** è disponibile per il ritiro presso i nostri sportelli. \nPuoi consultare gli orari sul [Portale del servizio](https://www.miosito.it/).\n\n*Lo Staff* |
If you are sending a **message with remote content**, refer to [#important-information-about-the-body-markdown-of-the-message](../../function/send-a-message/send-a-message-remote-content.md#informazioni-importanti-circa-il-corpo-markdown-del-messaggio "mention") for details about what to enter in this field.
When you create and send the text of the message in markdown format, remember to set the charset UTF-8, to make sure that the accented characters are displayed correctly.
You can format text and enable special functions in your messages using [the Markdown syntax](../../useful-resources/guide-to-the-markdown.md).
require_secure_channels
due_date
| |
|---|
| Description | This allows associating a reminder with the message. The format must be ISO-8601 with the UTC time zone |
| Mandatory | No |
| Type | String |
| Example | 2018-10-13T00🕛️00.000Z |
**Pay attention to the time zone!** The date must be expressed in the UTC (Z) time zone. In Italy, the time zone UTC+1 is used during Daylight Saving Time, whereas the time zone UTC+2 is used during Standard Time.
Example:
2022-09-30T22:00:00Z --> In Italy, it is midnight of October 1, 2022
2022-11-30T23:00:00Z --> In Italy, it is midnight of November 1, 2022
**Pay attention to the time!** If the expiration date does not have a specific time, usually it refers to the end of the day. Enter the time correctly to prevent displaying an incorrect due date.
Example:
✅ January 12 (23:59:59) --> the user can pay by January 12
❌ January 12 (00🕛️01) --> the user can pay by January 11
The expiration date of the message is separate of the due date of an associated amount that is due and can be specified also without the latter
If you signed the Premium agreement, IO will generate a [reading](https://docs.pagopa.it/kb-enti-messaggi/domande-frequenti/domande-e-risposte-sui-messaggi#come-funziona-il-reminder-per-i-messaggi-non-letti) or [payment](https://docs.pagopa.it/kb-enti-messaggi/domande-frequenti/domande-e-risposte-sui-messaggi#come-funziona-il-reminder-per-i-messaggi-con-avvisi-non-pagati) **reminder** close to the indicated due date: the reminders will be sent to the device of the recipient as push notifications
payment_data
To send payment notices, you must specifically request [authorization.](../../enabling/test-sending-pagopa-notices.md)
amount ``*
| |
|---|
| Description | Amount in euro cents of the payment notice issued on the pagoPA platform |
| Mandatory | Yes, for pagoPA payments |
| Type | Integer |
| Example | 100 |
notice_number ``*
| |
|---|
| Description | Notification code for a payment notice issued on the pagoPA platform |
| Mandatory | Yes, for pagoPA payments |
| Type | String |
| Example | 301011100007347557 |
It is important that the fiscal code of the sending service corresponds to the fiscal code of the payee that issues the pagoPA notice.
invalid_after_due_date
This feature is reserved for institutions that have agreed with PagoPA to enable the separation of the fiscal codes of the sender and the beneficiary of the amount due.
third_party_data
configuration_id ``*
For more information please refer to the section [remote-configuration.md](../../initial-setup/remote-configuration.md "mention")
id ``*
| |
|---|
| Description | Univocal third party identifier generated by the institution that is needed in order to associate the message with its remote contents |
| Mandatory | Yes |
| Type | String |
| Example | 2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91 |
has_precondition
If populated, the value of this field redefines, for the current message, the default behavior specified during configuration (for more information refer to [remote-configuration.md](../../initial-setup/remote-configuration.md "mention"))
has_remote_content
has_attachments
original_sender
original_receipt_date
summary
prescription_data
This function is being tested in house.
eu_covid_cert
This function is reserved to authorized persons.
legal_data
This function is being tested in house.
Examples
Non-remote message (static)
1### REQUEST curl --location --request POST 'https://api.io.pagopa.it/api/v1/messages' \ --header 'Content-Type: application/json' \ --header 'Ocp-Apim-Subscription-Key: __YOUR_API_KEY__' \ --data-raw '{ "content": { "subject": "Welcome new user !", "markdown": "# This is a markdown header\n\nto show how easily markdown can be converted to **HTML**\n\nRemember: this has to be a long text." }, “feature_level_type”: “STANDARD”, "fiscal_code": "AAAAAA00A00A000A" }'
2
Message with remote subject and markdown
1{ "content": { "subject": "Subject of the message shown in inbox", "markdown": "This text will be replaced by the remote markdown specified at the moment of using the message", "third_party_data": { "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91", //----------------------------------------------------- "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3", "has_remote_content": true //----------------------------------------------------- } }, "fiscal_code": "AAAAAA00A00A000A" }
2
Message with preconditions
1{ "content": { "subject": "Subject of the message", "markdown": "Message text with minimum length of eighty characters with respect to the IO integration specifications", "third_party_data": { "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91", "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3", //---------------------- "has_precondition": true //---------------------- } }, "fiscal_code": "AAAAAA00A00A000A" }
2
Remote message with attachments
1{ "content": { "subject": "Subject of the message", "markdown": "Message text with minimum length of eighty characters with respect to the IO integration specifications", "third_party_data": { "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91", "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3", //--------------------- "has_attachments": true //--------------------- } }, "fiscal_code": "AAAAAA00A00A000A" }
2
In the [#third_party_data](submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md#third_party_data "mention") block, it is possible to specify multiple combinations of the flags [#has_precondition](submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md#has_precondition "mention"), [#has_remote_content](submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md#has_remote_content "mention") and [#has_attachments](submit-a-message-passing-the-user-fiscal_code-in-the-request-body.md#has_attachments "mention") (the latter only if you have signed the agreement related to [premium-functions.md](../../enabling/premium-function.md "mention")), as shown in the example:
1{ "content": { "subject": "Subject of the message", "markdown": "Message text with minimum length of eighty characters with respect to the IO integration specifications", "third_party_data": { "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91", "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3", //------------------------- "has_precondition": true, "has_remote_content": true, "has_attachments": true //------------------------- } }, "fiscal_code": "AAAAAA00A00A000A" }
2
IO performs consistency checks between the flags indicated in this step and what is returned with the remote message details; as an example, if you indicate `"has_attachments": true` but when retrieving the message details do not include the structure `"attachments"`, your recipient will receive an error and will not be able to view the message.
Expected response
In all the cases described above, IO returns the identifier of the message that you can use to query the status via the API
Get Message.
1{ "id": "01EM6X4JB9VSZTQ8H16KMQFCEJ" }
2
If you have signed a Premium agreement, in addition to knowing if a message was sent correctly, you can know the read status and, if present, the payment status of the associated amount due.
💡 It is important that your systems are instructed to **keep the identifiers of the messages sent with IO**, maintaining the correlation with the respective recipients and any remote context information.
Useful resources
